smart spec boot loader

Automation and Drives

A&D AS RD DH F Human Machine Interface Systems

SmaRT

Architecture

Under Construction

Design Specification

Bootloader SmaRT

PNB: /tt/file_convert/55213d0b4a795976718b4ac3/document.doc

Authors:Role Name Department Date SignatureAuthor Thomas Eschenbacher evosoft GmbH 2008-03-13

( Revision 0.9 of this document has been released.

Released by:Role Name Department Date SignaturePL Kardas, Dario A&D AS RD DH FPM

QA

Abstract

This document describes the function of the bootloader for OP73, OP77A, TP177, HT2, KTP400/600/1000/1500.

For internal use only

Copying of this document and giving it to others and the use or communication of the contents thereof are forbidden without written permission. Offenders are liable to the payment of damages. All rights are reserved in the event of the grant of a patent or the registration of a utility model or design.

Revision: 0.9.3 2007-12-17 of 32 document.doc

© Siemens AG 2008 All Rights Reserved

A&D AS SmaRT Bootloader SmaRTDesign Specification

Table of Contents

1 Scope of this document..................................................................................................5

2 Startup Sequence.........................................................................................................5

2.1 Constraints.............................................................................................................6

2.2 Actions on startup..................................................................................................6

2.3 Main loop.................................................................................................................6

3 Image Processing.........................................................................................................7

3.1 Order of processing...............................................................................................7

4 Image Header................................................................................................................84.1.1 Image Header Structure............................................................................................................8

4.1.2 Usage of the Image Header Fields...........................................................................................8

4.1.3 Image Types............................................................................................................................ 10

4.1.4 Image Attributes...................................................................................................................... 10

4.2 Extension of the Compression Algorithm to support Streaming....................11

4.3 Image Chaining / Fragments...............................................................................124.3.1 Order of processing................................................................................................................12

4.3.2 Usage of dwImageAreaSize....................................................................................................12

4.4 CRC checks..........................................................................................................12

4.5 Copy from Flash to Flash....................................................................................13

4.6 Uncompress from Flash to Flash........................................................................13

4.7 Copy from Flash to RAM.....................................................................................13

4.8 Uncompress from Flash to RAM.........................................................................13

4.9 Validity check.......................................................................................................14

4.10 Switch to Runtime or Hardware-Test..................................................................144.10.1 Passing Command Line Parameters to the Application......................................................14

4.10.2 MTD mapping per command line...........................................................................................15

4.10.3 Flash Directory........................................................................................................................ 15

4.10.4 Preconditions for starting an Operating System..................................................................16

5 Serial Transfer............................................................................................................17

6 Serial Telegram...........................................................................................................19

6.1 Available commands............................................................................................19

6.2 Answers from device...........................................................................................20

6.3 Error Correction...................................................................................................21

6.4 Timing....................................................................................................................21

6.5 Typical initial connection....................................................................................21

6.6 Compression........................................................................................................236.6.1 Compressed telegram-structure:...........................................................................................23

6.6.2 Compression algorithm:.........................................................................................................23

7 Pointer to Hardware info and Flash Directory.........................................................25

7.1 Hardware Info.......................................................................................................25

7.2 Flash directory / Flash settings...........................................................................25




8 Device Specifica.........................................................................................................26

8.1 OP 73micro, OP73 micro-debug and OP 73.......................................................26

8.2 OP 77A...................................................................................................................26

8.3 HT2.........................................................................................................................27

8.4 TP 177 family........................................................................................................27

8.5 KTP1000 Basic / TP1500 Basic family...............................................................28

8.6 KTP400 Basic / KTP600 Basic family.................................................................29

9 Examples of typical Image Headers.........................................................................30

9.1 Runtime under eCos............................................................................................30

9.2 Hardware test for TP 177.....................................................................................30

9.3 Linux Kernel for OP 77A......................................................................................30

9.4 Root Filesystem for TP 177.................................................................................31

9.5 Configuration data for OP 73, stored in transfer area.......................................31

9.6 Abbreviations.......................................................................................................32

10 Bibliography..................................................................................................................32




History of Changes

Revision Date Changed parts and reason Name Department0.1 2003-10-20 Initial issue Michael Frommberger sympat GmbH0.3 2003-11-27 updates of protocol spec Michael Frommberger sympat GmbH0.4 2004-03-18 added chapters about bootloader

operationTh. Eschenbacher sympat GmbH

0.5 2004-06-24 processing of images and fragements Th. Eschenbacher sympat GmbH0.6 2004-10-11 special handling for HW-test Th. Eschenbacher sympat GmbH0.7 2004-11-05 mtd partitioning per command line Th. Eschenbacher sympat GmbH0.8 2005-08-01 support of error correction added Michael Frommberger sympat GmbH0.9 2005-08-19 increment of package count on error

addedMichael Frommberger sympat GmbH

0.9.1 2007-08-06 added XP179 and MAP1, removed ISAC-73 and ISAC-73 TC, added chapter for device specifica, added XP179 and MAP1

Th. Eschenbacher evosoft GmbH

0.9.2 2007-09-11 new device names:- MAP1 4” → KTP400 Basic- MAP1 6” → KTP600 Basic- XP179 10” → KTP1000 Basic- XP179 15” → KTP1500 Basic

Th. Eschenbacher evosoft GmbH

0.9.3 2007-09-24 renamedKTP1500 Basic to TP1500 Basic

R. Stiegler evosoft GmbH

0.9.4 2007-12-17 added cmdline for MAP1 Th. Eschenbacher evosoft GmbH0.9.5 2008-03-13 more cmdline parameters for MAP1 Th. Eschenbacher evosoft GmbH

The current revision invalidates all former document revisions.

ResponsibilityResponsible for the coordinated contents are:

Name Department Location Tel Signature DateTh. Eschenbacher evosoft GmbH Fürth 0911/978 - 3167

Distribution list

Distributed to: For attention:

Name Department Location Name Department LocationDario Kardas A&D AS RD DH F Th. Eschenbacher evosoft GmbH FürthMichael Minden A&D AS RD DH F R. Stiegler evosoft GmbH Fürth




1 Scope of this documentThe bootloader’s primary task is to completely initialize the hardware of the device and to start the installed operation system. Furthermore it provides a way of restoring or initially filling the device’s flash when the operating system is damaged or not yet present, through a serial transfer.

This document describes the function of the bootloader for the all SmaRT devices. It also describes the serial transfer and the compression algorithm used in it.

2 Startup SequenceThe following sections describe the actions that the bootloader performs.

figure 1 program flow of the SmaRT bootloader




2.1 ConstraintsFor the startup sequence, several constraints have to be met and some worst-case scenarios have to be considered. These will be discussed below:

The bootloader ist the only place where all I/O-ports of the CPU and all peripheral units of the board has to be done, no hardware initialization should be done later in the application.

The bootloader has to give a feedback to the user as soon as possible after the power-up, to show that the board is “on”.

In case the whole flash of the board (except the bootloader itself) is erased or filled with invalid data, it must provide a way to recover the device. Therefore the bootloader has to wait for a serial transfer before it starts application code or evaluates the content of the flash.

In case the bootloader crashes while processing invalid or damaged flash content (images), it must provide a way to recover. As a consequence, the bootloader has to wait for a remote transfer before processing images from flash.

Before starting the application, all images in flash which need processing have to be processed.

2.2 Actions on startupWhen the bootloader starts up, it does the following things:

1. eCos startup: Initialize all I/O-ports of the CPU (in ARM 32bit mode), switch to Thumb mode (optionally), Initialize interrupt controller, system timer and enable cache (optional).

2. if it is the first startup, which is detected if hardware info (HW) is not valid:a. unprotect the bootloaderb. create the common flash info (CFI)c. create the hardware infod. protect the bootloader

3. Initialize the display

2.3 Main loopAfter this initialization it enters an infinite loop with the following sequence:

1. If required: wait for a remote connection, switch to transfer mode if necessary. Timeout 6 seconds.2. Process all images found in the flash, move them to different locations if necessary.3. Check if a hardware test is present in the configuration area of the flash and start it if found.4. Check if an operating system or application is present and start it if found.




3 Image ProcessingNote: All portions of memory in the flash that require treatement, interpretation or execution, except the bootloader itself and the settings storage (chunks) are called “image” in the context of the bootloader.

The following sections describe the basic operations and features that the bootloader provides for processing images.

3.1 Order of processingImages are searched at a defined set of positions in the flash, which is stored in a so-called “flash directory” in the settings area of the flash. The flash directory is located at a device- and variant-dependend location in the flash. A pointer to the flash directory is stored at memory location 0x0000.0024 for ARM devices. The structure of the flash directory is described in the document “Smart_FlashServices.doc” [2]

The search is using a fixed order and relies on the entries in the flash directory, using the given chunk name as index, in the following order:

1. configuration area (@CFG) special treatment: If this area contains a hardware test, all following areas are skipped !

2. transfer area (@TRA)3. runtime area (@RT_)4. filesystems (@FS0 ... @FS9)

If a chunk is not listed in the flash directory, it will be silently skipped.




4 Image HeaderFor providing a certain compatibility with former SIEMENS applications, the current bootloader implementation re-uses the same structure for image headers as for windows CE devices.

4.1.1 Image Header Structure

The image header is defined as following (defined in btstrct.h). It’s elements are defined to be in little-endian format, so for accessing them on a big-endian machine, byte/word-swapping has to be done!

/** * Structure for describing a CE (or smart) image. */#pragma pack(1)typedef struct{ u_int32_t dwSignatur; // [0] Signature of the Structure u_int16_t wDescVer; // [4] version number of the structure u_int32_t dwRunAdr; // [6] start adress in RAM/Flash u_int32_t dwStoreAdr; // [10] start adress in Flash u_int32_t dwOrgLen; // [14] ungepacked image length u_int32_t dwCompLen; // [18] packed image length u_int16_t wOrgChkSum; // [22] CRC of the original image u_int16_t wCompChkSum; // [24] CRC of the packed image u_int16_t wVersionMajor; // [26] major part of image version, u_int16_t wVersionMinor; // [28] minor part of image version u_int32_t dwVersionImage; // [30] build, distinction of debug/release u_int32_t dwVersionApp; // [34] version of application within image u_int32_t dwEntryPoint; // [38] entry point for executable u_int16_t wImageAttrib; // [42] attributes of image handling struct ImageDesc *pNextDesc; // [44] pointer to next descriptor u_int32_t dwImageAreaSize; // [48] length of packed image area u_int32_t dwTypeImage; // [52] image-type u_int16_t wTargetHW; // [56] target hardware for CE-image u_int8_t reserved[CE_IMAGE_DESC_SIZE - 59]; // reserved for future use u_int8_t byReboot; // image loaded, reboot neccassary } ce_image_desc_t;#pragma pack()

Table 1 CE image header

4.1.2 Usage of the Image Header Fields

The elements of this structure has to be interpreted as follows.

dwSignatur: always contains the signature “CE00” as a four-character ASCII sequence. In hexadecimal this is the word 0x30304543.

wDescVer: version number of the structure’s version. This is provided as a way of keeping compatibility with newer versions of the structure which might have a different size or different content (except these first two fields)




dwRunAdr: address where the content should be stored (or running), where the CPU expects the image’s contents. If this address is different from the following field dwStoreAdr, this means that the bootloader has to copy it to a different location before it can be used. If the target address is in RAM, it specifies the start address of the content immediately following the image header. If the target address is in flash, it specifies the address where the whole image, including the header has to be copied.

dwStoreAdr: address where the content has to be laid within persistens storage. If this field does contain an address that is different from the current position of the image header, the bootloader has to copy/unpack the image to that position. If the target address is in flash, the content will not be unpacked.

wOrgLen: length of the image, always including the size of the header (even if IMAGE_OS_SPLIT is used).

wCompLen: length of the compressed image, always including the size of the header.

wOrgChkSum: CRC of the original image, not including the header. If the image is only a fragment of a bigger image, only this current portion is used for the CRC calculation. Corresponds to wOrgLen or wOrgLen, minus size of the header in case of a IMAGE_OS_SPLIT.

wCompChkSum: like before, CRC of the image after compression, corresponds to wCompLen.

wVersionMajor, wVersionMinor, dwVersionImage, dwVersionApp: can be used the same way as in CE images, not interpreted by the bootloader

dwEntryPoint: if the image is something that the bootloader has to execute, this specifies the address (as seen by the CPU) where it should jump to. If this address is unused (e.g. for configuration data), this address should be initialized with zero, which means “not specified / invalid”.

wImageAttrib: holds attributes that define which actions have to be performed by the bootloader with this image. Will be explained in the following section. See section 4.1.4

pNextDesc: pointer to the start of next image header (address as seen by the CPU). This allows chaining of images in different areas of the flash, which is described in section . If this is the only image or the last image in a chain, this field must contain the special value 0x0000.0000.

dwImageAreaSize: holds the size of the whole, composed, image in case of a split image. In this case it is the sum of all fragments. It should be present only in the first fragment. For all other fragments in a chain or an unfragmented image it should be equal to the wOrgLen field.

dwTypeImage: defines the type of the image’s content. Possible types are “application”, “operating system”, “hardware test” or “split/fragment”. See section 4.1.3

wTargetHW: bitfield for the supported hardware platforms on which this image can be used. For Smart devices, this field always contains the special value 0x800F (Smart Device, unknown variant). This is not interpreted by the bootloader and only checked to be non-zero. As we do not have additional device information, it is up to the PC side to not provide any image that does not match the device.

reserved: these fields are reserved for future use and are filled with 0xFF. They are not interpreted by the booloader.

byReboot: If an image has set this byte to a non-zero value, the bootloader will reboot the device after it has processed all images. All “byReboot” flags of all images that have been processed will be logically “OR”ed.




4.1.3 Image Types

The bootloader knows about definitions for the following image types, which can be combined as a bitmask:

/* img_type */#define IMAGE_NONE 0x00000000 /**< image type none */#define IMAGE_OS 0x00000001 /**< OS image */#define IMAGE_OS_INPLAOS 0x00000002 /**< for demonstration only, not used! */#define IMAGE_OS_SPLIT 0x00000040 /**< splitted part of os_image */#define IMAGE_APP 0x00010000 /**< application (runtime) image */#define IMAGE_HWT 0x80000000 /**< hardware-test */#define IMAGE_OS_APP (IMAGE_OS | IMAGE_APP) /**< OS and App */

Table 2 Image Types

IMAGE_NONE: used for all images that are neither application/hardware-test nor operating-system. It is also used for non-executable data, like configuration or receipt data.

IMAGE_OS: operating system image. IMAGE_OS_SPLIT: splitted part / fragment of operating system.

Note: For SmaRT devices, it is also allowed to mark fragments of other image types. This flag is needed by the bootloader to determine if it has to omit the copying of the image header in case of the transfer of an image fragment (see discussion of chaining / fragments in section 4.3)

IMAGE_APP: application, runtime, or whatever is supposed to run on the device. IMAGE_HWT : hardware-test, which has precedence over the application and/or operating system if

there are multiple possible images that could be executed. IMAGE_OS_APP: combined image with operating system and application (e.g. runtime running with

eCos)

For historical reasons, these definitions are implemented in “img_hdr.h”.

4.1.4 Image Attributes

The bootloader knows about definitions for the following image attributes, which can be combined as a bitmask:

#define ATTR_INPLACE 0x0000 /**< execute/use in place */#define ATTR_UNPACK 0x0001 /**< stored compressed */#define ATTR_COPY_RAM 0x0002 /**< copy to RAM */

Table 3 Image attributes

ATTR_INPLACE: the image can be used where it is ATTR_UNPACK: the image is compressed ATTR_COPY_RAM: the image has to be copied to RAM before it can be used




4.2 Extension of the Compression Algorithm to support StreamingFor saving code space, the bootloader should use the same algorithm for decompressing images as it uses for decompressing packets from the serial transfers (see description in chapter 6.6.2).

Unhappily the standard compression algorithm of the bootloader (and it’s implementation), is only suitable for compressing blocks of memory, not continuous streams. As the bootloader does not have enough memory to hold large buffers needed for transferring big images, there is the need for a way of compressing images in units of small blocks and a scheme for decompressing streams.

The streaming algorithm works as follows (see Figure 2 below):1. read 32768 bytes from the source into a buffer (inbuffer)2. compress (pack) the inbuffer to an output buffer (outbuffer), using the algorithm described in chapter

6.6.2) The outbuffer should have the same size as the input buffer, for coping the worst case of incompressible data.

3. write the size of the compressed block into the output, using 16-bit little endian format.4. write the compressed data into the output device or stream5. if the size of the compressed output is not properly aligned, pad it with uncompressed original data

(bytewise), either from the remaining rest of the compression input buffer (5a) or from the stream with uncompressed data (5b). If the end of the source has been reached, pad with 0xFF.

6. if the compressed data did not fit completely in the outbuffer, goto step 2 and compress the remaining rest.

Figure 2 Algorithm for compressing streams




4.3 Image Chaining / FragmentsImage chaining / usage of fragmented images can be used to assemble on big image from several little parts. An example for this is an operating system update, which consists of two image fragments, one stored in a configuration area and one in a transfer area, which are then assembled to one big operating system image.In addition to this, it is also possible to use this mechanism to chain images in one area, without the need for the bootloader to look into different entry points to search for images/fragments to process.Images in one chain therefore do not necessarily need to belong to one and the same big image, several images and/or fragments with different types can be mixed in one chain and produce several bigger target images or single images.

4.3.1 Order of processing

The bootloader’s function for processing an image first cecks if the pNextDesc field of the image eader is non-zero and if so, it calls itself recursively with the pNextDesc pointer as start address. This way a chain will always be processed from the end (last element in the chain) up to the start (first element in the chain).

4.3.2 Usage of dwImageAreaSize

All fragments of a split bigger image, except the first one, are treated like any other image. To signal that an image is a fragment, the IMAGE_OS_SPLIT flag in dwTypeImage must be set, which prevents the image’s header from being copied. The dwImageAreaSize of a subsequent fragment is equal to the uncompressed size of the fragment itself.

The first fragment (head) of a chain can have the IMAGE_OS_SPLIT flag in dwTypeImage set, but does not need to, it depends on whether the header has to be copied or not. In case of an uncompressed image, the dwImageAreaSize of the chain’s head can only reflect the size of the first fragment. In case of a compressed image, the head contains the size of the whole image, which has been assembled from all it’s fragments.

The special handling of CRCs has to be taken into account, like described in chapter 4.4 !

4.4 CRC checksWhen checking an uncompressed image, the CRC is taken from wOrgChkSum and covers the range that is specified by the dwImageAreaSize field. dwCompLen and wCompChkSum are not used. The dwOrgLen field has no importance for the CRC, it is only used for the the transfer operation itself (amount to copy/process).

When checking a compressed image, the length of the area to check is taken from dwCompLen and the CRC from wCompChkSum is used. dwImagAreaSize and wOrgChkSum are ignored when checking the compressed image, they only get their meaning when the uncompressed result has to be checked.

Consequences: If the image was uncompressed but fragmented, the CRC would then only cover the first fragment,

and therefore it would be less secure than in case of an image that has been assembled out of compressed fragments.

In case of compressed fragments, the CRC of the resulting image will span the whole image, over the whole size from dwImageAreaSize, giving better security.

Conclusion: it is highly recommended to use compression at least for the first fragment of a chain, even if this does not save space - but this increases security of the system!

By having (at least) the first fragment compressed, it is still possible to do a CRC check of the fragment itself before processing, because the compressed CRC (wComChkSum) covers only the fragment itself. After processing (uncompressing), the CRC (wOrgChkSum) will cover the whole image, including all previously processed fragments.




4.5 Copy from Flash to FlashCopy an image 1:1 from flash to flash. If the image is part of a chain (IMAGE_OS_SPLIT flag in dwTypeImage is set), the operation is done in “headerless mode”.

source address: current position ( + size of header in headerless mode) source length: dwOrgLen ( - size of header in headerless mode) destination address: dwStoreAdr destination length: same as source length header modifications: none operation: blockwise, 64kB per block

4.6 Uncompress from Flash to FlashUncompress an image from flash to flash. If the image is part of a chain (IMAGE_OS_SPLIT flag in dwTypeImage is set), the operation is done in “headerless mode”. The compression/decompression algorithm is described in chapter 4.2.

source address: current position ( + size of header in headerless mode) source length: dwCompLen ( - size of header in headerless mode) destination address: dwStoreAdr destination length: dwOrgLen ( - size of header in headerless mode) header modifications: ATTR_UNPACK in wImageAttrib is reset to zero operation: blockwise, depending on compression

4.7 Copy from Flash to RAMCopy an image 1:1 from flash to RAM. If the image is part of a chain (IMAGE_OS_SPLIT flag in dwTypeImage is set), the operation is done in “headerless mode”.

source address: current position ( + size of header in headerless mode) source length: dwOrgLen ( - size of header in headerless mode) destination address: dwStoreAdr destination length: same as source length header modifications: none operation: blockwise, 32kB per block

4.8 Uncompress from Flash to RAMCopy an image 1:1 from flash to flash. If the image is part of a chain (IMAGE_OS_SPLIT flag in dwTypeImage is set), the operation is done in “headerless mode”.

source address: current position ( + size of header in headerless mode) source length: dwOrgLen ( - size of header in headerless mode) destination address: dwStoreAdr destination length: same as source length header modifications: ATTR_UNPACK in wImageAttrib is reset to zero operation: blockwise, depending on compression




4.9 Validity checkBefore and after being processed (like described in the chapters 4.5, 4.6, 4.7 and 4.8) each image is checked for validity.

An image is considered to be valid if it meets all of the following conditions:1. the memory address is not zero2. the memory address is aligned to 32 bit (4 byte)3. the memory address is within RAM or within the flash4. the header starts with a valid signature (dwSignatur)5. dwOrgLen is not zero6. dwImageAreaSize is not zero7. wTargetHW is not zero8. wDescVer is higher or equal to one9. in case of an uncompressed image: the CRC over dwImageAreaSize matches wOrgChkSum

in case of a compressed image: the CRC over dwCompLen matches wCompChkSum10. the size of the image is less than the biggest block of memory on the device (RAM / Flash). For

current SmaRT devices of the OP73 family and TP177 family this limit is set to 16MB.

4.10 Switch to Runtime or Hardware-TestThe conditions for the transition from the bootloader to the application (bootloader, hardware test, etc.) are as follows:

1. the hardware of the board is completely initialized (not including the peripherals on the debug board)2. the CPU is switched into ARM 32 bit mode, supervisor mode

(Note: the bootloader operates in thumb mode, switching is done by a “BX” assembler instruction)3. IRQ is disabled4. FIQ is disabled5. Cache is enabled6. the register R0 holds a pointer to a command line, see chapter 4.10.17. the display is cleared8. the display contrast is set to it’s default value9. the serial port 0 is set to RS485 mode, with 9600 Baud, no parity, 1 stop bit10. the serial port 0 transmitter is disabled

4.10.1 Passing Command Line Parameters to the Application

The bootloader can pass a pointer to a command line string to the application (e.g. runtime) through the processor register R0 or any other application or board specific data. This is device specific and described in chapter 8.




4.10.2 MTD mapping per command line

The SmaRT bootloader after v0.22 parses the flash directory of the device into command line suitable for the uCLinux mtd cmdline partitioning driver.

It supports a mapping with read-only and read/write areas. Read-only areas are treated as “ROM” and read-writeable areas are treated as “flash”.

The syntax of the command line is as follows: mtdparts=<mtddef>[;<mtddef] <mtddef> := <mtd-id>:<partdef>[,<partdef>] <partdef> := <size>[@offset][<name>][ro] <mtd-id> := unique id used in mapping driver/device, either “rom” or “flash” <size> := size of the area in kB <name> := '(' NAME ')'

Table 4 MTD commandline syntax

Example:mtdparts=rom:64k@0x0(@HWI)ro,448k@0x10000(@RT_)ro;flash:512k@0x00000000(@CFG), ...

For generating a command line with MTD mapping entries, the bootloader relies on a valid flash directory, which is described in the following section.

4.10.3 Flash Directory

The flash directory is a chunk within the “settings” area of the SmaRT system and consists of one single chunk with a variable sized array of flash directory entries.

One flash directory entry has four 32bit fields, which are encoded in the target’s CPU endianess:

offset field description0x00 ckid Chunk ID0x04 ckaddr physical start address of the area0x08 cksize size of the area in bytes0x0C ckdevice Bit 31 0 = read/write

1 = read-onlyBit 30…0 eCos: not used, set to 0x0000001

µClinux / Linux: number of the MTD device [0…n-1]

Table 5 Flash Directory

Constraints for a suitable flash directory:

1. The first entry must start at the start address of the flash device2. Entries must be ordered by the start address, upwards3. The list must not contain gaps. Gaps must be filled with spare entries “@SPA1...n”4. The µClinux/Linux device numbers must be ordered and must not contain gaps.5. The start address of area “N+1” must be the start address of area “N” + the size of area “N”6. All addresses are referring to the bootloader’s address mapping. In non-MMU systems these are

equal to the physical address, in MMU systems the address mapping that the bootloader has set up applies.




4.10.4 Preconditions for starting an Operating System

If the application is an operating system or application (not hardware test) and the device’s flash directory contains entries for filesystems (“@FS0”…”@FS9”), all filesystems that are listed in the flash directory must be present and consistent.

The consistency check is currently only implemented on a very basic/incomplete level. The filesystem type is detected and checked as follows:

1. first 4 bytes are 0xFFFFFFFF empty, not used, no filesystem, no further check (failed)

2. area starts with 0x30304543 (little endian, ASCII “CE00”) SmaRT image header, check image integrity

3. area starts with ASCII string “-rom1fs-“ ROMFS, currently no further checks.

4. area starts with 0x28CD3D45 (CPU endianes) CRAMFS, only checking for signature at offset 0x10 (ASCII string “Compressed ROMFS”), currently no further checks

5. all other content, image address is zero or not 32-bit aligned not valid




5 Serial Transfer

At start of the serial transfer the bootloader tries to establish a communication-link via RS485-interface to an external client (baudrate: 9600 baud). If there is no response within the timout intervall, the image will be loaded immediately if it is present and valid, otherwise the device keeps on waiting for a connection on the serial port.

If the communication attempt with the default baudrate has been successfully established, the baudrate will be increased by the client and the device detects the new transfer-speed. Afterwards the data is received, the data from header and checksum separated und the commands are processed.The bootloader ends when an OS image is started or the commands BOOT_CMD_END_BOOT_LOADER or BOOT_CMD_CANCEL_BOOT_LOADER are received.





START

check state of OS image

in flash

try to comm-unicate with

client

comm. successfull

?

detect baudrate

yes

no

receive telegram

do command

end of telegram?

no

END

yes

load OS or App from

flash

START

check state of OS image

in flash

try to comm-unicate with

client

comm. successfull

?

detect baudrate

yes

no

receive telegram

do command

end of telegram?

no

END

yes

load OS or App from

flash



6 Serial Telegram

Telegram-structure:

0--------16----24----32----------------64----------------96--------112-----------------------(length -16 bit)--------length

--- header--- data--- checksum

Position [bit] Length [bit] Meaning0 – 14 15 Length

15 01 Compression16 – 23 08 Command24 – 31 08 EMS32 – 63 32 start-address64 – 95 32 Range

96 – 111 16 position-index112 - (length-16 bit) 16 – 4096 Data

(length-16 bit) - length 16 CheckSum

6.1 Available commands

command Item meaning0x0001 BOOT_CMD_READ reads specified data and sends it back0x0002 BOOT_CMD_WRITE writes telegram-data to memory0x0003 BOOT_CMD_ERASE_FLASH erase specified part of flash0x0006 BOOT_CMD_GET_CHKSUM calculates checksum of specified memory-part0x0004 BOOT_CMD_END_BOOT_LOADER terminates bootloader0x0008 BOOT_CMD_CANCEL_BOOT_LOADER cancel bootloader0x0007 BOOT_CMD_GET_SW_INFO nu0x0005 BOOT_CMD_END_LOADER nu0x0009 BOOT_CMD_CANCEL_LOADER nu0x000A BOOT_CMD_ERROR nu0x0040 RAM_LADER_CMD nu




6.2 Answers from device

ACK item meaning source0x0001 BOOT_ACK_READ reading from memory was

successfullCmdReadMem

0x0002 BOOT_ACK_WRITE writing to memory was successfull CmdWriteMem0x0003 BOOT_ACK_ERASE_FLASH erasing flash was successfull CmdEraseFlash0x0004 BOOT_ACK_END_BOOT_LOADER bootloader will terminate CmdEndBootLoader0x0005 BOOT_ACK_END_LOADER nu nu0x0006 BOOT_ACK_GET_CHKSUM calculation of crc was successfull CmdGetChkSum0x0007 BOOT_ACK_GET_SW_INFO nu nu0x0008 BOOT_ACK_CANCEL_BOOT_

LOADERbootloader will be canceled CmdCancelBoot

Loader0x0009 BOOT_ACK_CANCEL_LOADER nu nu0x000A BOOT_ACK_ERROR tbd tbd

error Item meaning parameter 1 parameter 2 source 0x01 ERR_CANCEL_ON_OP nu nu nu nu0x03 ERR_TEL_CHKSUM Incorrect crc 0 0 btld_process_

command0x04 ERR_TEL_INDEX false positon-index expected

position-indexreceived

position-indexbtld_process_

command0x05 ERR_UNKNOWN_CMD unknown command

receivedreceived

command0 btld_process_

command0x06 ERR_FLASH_PROG try to write to invalid

flash address1 / 0xa55a hi-word of

start-addressCmdWriteMem

0x07 ERR_INVALID_ADR_RANGE

try to write to invalid address-range

hi-word of start-address

low-word of start-address

CmdWriteMem

0x08 ERR_SIZE_ADR_RANGE

size of requested memory too big for

sending in one telegram

hi-word of range

low-word of range

CmdReadMem

0x09 ERR_FLASH_ERASE try to erase invalid flash adress

1 / 0xa55a hi-word of start-address

CmdEraseFlash

0x0a ERR_UART nu nu nu nu0x0b ERR_INIT_FLASH_

ROUTINEnu nu nu nu

0x0c ERR_FORCE_TRANSFER

nu nu nu nu

0x0d ERR_DECOMP decompression of packet failed

0 0 btld_process_command

0x0e ERR_INCOMPLETE_PACKET

packet not completely received

0 0 btld_peek_command

0x0f ERR_RETRY max retry count reached 0 0 bltd_process_command / btld_peek_command

6.3 Error CorrectionIn the following error-cases we request an resend of the whole telegram:




– ERR_TEL_CHKSUM : we received everything but the checksum seems not to match– ERR_DECOMP: we have problems with decompression of the packet (e.g. the decompressed packet is

smaller than the compressed one...)– ERR_INCOMPLETE_PACKET: we already received the length of the packet, but the rest is not here

within the timeout.The maximum count of retries are 2 re-requests with the packet-count incremented on every packet sent. Is there still an error afterwards, an retry-error is signalized and the communication stops.

6.4 Timing

Initial connection (default baudrate: 9600 baud):maximum time to connect 2000 msminimum time between received packets 30 msInitial connection-signature: 0xAAFFAAFFAAFFAAFF ….

Receiving signature:maximum time to get signature 100 ms

Normal communication:Time to answer request 10 s

Connection established:delay between packets tbd (depends on baudrate)timout tbd

Available baudrates [baud]:

1200 9600 1152001800 19200 2304002400 384004800 57600

6.5 Typical initial connection

0. seeking for client1. baudrate detection2. request for hardware-info-address3. request for hardware-info4. request for OS-image-header

Example:

--- answer from OP--- request from ProSave

0. port opened by "PTProSave.exe (PID: 884)

AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU




AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU AA FF AA FF AA FF AA 55 AA FF AA FF AA FF AA 55 ªÿªÿªÿªUªÿªÿªÿªU AA FF AA FF AA FF AA 55 ªÿªÿªÿªU

0. Answer: 24.11.2003 15:01:45.013125064 (+1.1562500000 seconds)

AA FF AA FF AA FF ªÿªÿªÿ

port closed

port opened by "PTProSave.exe" (PID: 884)

1. Request: 24.11.2003 15:01:45.200625064 (+0.1093750000 seconds)

00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 00 00 00 00 00 00 00 00 ........

1. Answer: 24.11.2003 15:01:45.841250064 (+0.1093750000 seconds)

AA ª

2. Request: 24.11.2003 15:01:46.013125064 (+0.1718750000 seconds)

10 00 01 00 EC FF FF 03 04 00 00 00 00 00 40 75 ....ìÿÿ.......@u

2. Answer: 24.11.2003 15:01:46.028750064 (+0.0156250000 seconds)

14 00 01 00 EC FF FF 03 04 00 00 00 01 00 00 00 ....ìÿÿ......... 04 00 36 37 ..67

3. Request: 24.11.2003 15:01:46.044375064 (+0.0000000000 seconds)

10 00 01 00 00 00 04 00 80 00 00 00 01 00 B3 0F ........€.....³.

3. Answer: 24.11.2003 15:01:46.060000064 (+0.0156250000 seconds)

48 80 3E 00 90 00 0B 60 00 00 00 90 00 01 00 00 H€>...`....... 00 04 00 40 80 06 10 02 00 A5 01 C0 BF 01 00 08 ...@€....¥.À¿... 20 FF FF FF 40 04 20 0A 00 00 20 01 1A 10 67 08 ÿÿÿ@. ... ...g. 10 06 7F 30 11 10 03 10 06 40 0C A0 18 F0 18 30 ..0.....@.� .ð.0 F0 30 03 10 00 5A 15 81 ð0...Z.

4. Request: 24.11.2003 15:01:46.138125064 (+0.0000000000 seconds)

10 00 01 00 00 00 C1 BF 40 00 00 00 02 00 79 52 ......Á¿@.....yR

4. Answer: 24.11.2003 15:01:46.153750064 (+0.0156250000 seconds)

34 80 2A 00 50 00 50 F5 00 00 00 50 00 01 00 00 4€*.P.Põ...P.... 00 C1 BF 40 40 06 10 03 00 C9 08 C9 08 C7 04 20 .Á¿@@....É.É.Ç. 04 20 C2 08 C2 0E 90 10 E0 10 E0 00 C9 08 C2 08 . Â.Â..à.à.É.Â. C2 08 47 ED Â.Gí




6.6 Compression

Every telegram can be received / sent compressed.

6.6.1 Compressed telegram-structure:

1--------16--------32--------48--------64--------80----------------------------------------------------------------------length

--- header--- data

Position [bit] Length [bit] Meaning00 – 14 15 Length

15 01 Compression16 – 31 16 Compressed data-length32 – 47 16 Uncompressed telegram-length48 – 63 16 Compressed CheckSum64 – 79 16 Uncompressed CheckSum

80 - length 4095 Data

6.6.2 Compression algorithm:

If the actual string has been already processed, generate 2 bytes which consists of offset and length:Bit 1 - 4 : length + 2 (value: 0 – 15)Bit 5 - 16: offset (value: 0 – 4095)If the length is greater than 15, a third byte is used for the length value:Bit 17 – 24 length (value: 0 – 65535)

1--4-----16-----24--- length (< 15 + 2)--- offset--- length ( > 15 +2)

The information if a group is compressed or not is stored in the first byte (packmask). Bit 7 decodes the first group, bit 6 the second etc. If the bit is 0 the length of the group is 1 Byte and the data is literal. If the bit is 1 the data is compressed.




Example:

Compressed: 48 80 3E 00 90 00 DF F1 00 00 00 90 00 01 00 00 00 04 00 40 80 06 10 02 00 A5 01 C0 BF 01 00 08 20 FF FF FF 40 04 20 0A 00 00 20 01 1A 10 67 08 10 06 7F 30 11 10 03 10 06 40 0C A0 18 F0 18 30 F0 30 03 10 00 5A 15 81

80 48 Compression (1) + length (0x48) 00 3E comp length (0x3E) 00 90 uncompressed length (0x90) DF F1 comp chksum (DF F1) 00 00 uncomp chksum (00 00)

decompressed: |------packmask-------| |----------------------------------------data-------------------------------------------------| 00 0000 0000 90 00 01 00 00 00 04 00 40 0100 0000 80 00 00 00 02 00 A5 01 C0 BF 01 0000 0001 00 08 20 FF FF FF 40 FF FF FF 40 0A 0000 1010 00 00 20 01 00 80 00 67 00 00 20 06 7F 0111 1111 30 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF

FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FFFF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FFFF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FFFF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF

FF FF FF 00 0000 0000 5A 15 81




7 Pointer to Hardware info and Flash Directory

7.1 Hardware InfoThe position of the hardware info structure can be queried by reading the 32bit value at offset 0x0000.0020, with the address given in the target endiannes (e.g. OP73 is big endian, TP177 family is little endian).

To be compatible with i386 devices and older versions of ProSave, we also support reading the address of the hardware info through reading at the i386 address 0x03FF.FFEC.

Important Note: the vector to the hardware info is not really located in the memory location at the offset described above. Instead the bootloader/transfer software “fakes” the content of this memory location and takes care of providing the real position of the hardware info.

This structure is defined in [1].

7.2 Flash directory / Flash settingsUnlike the hardware info, the memory address of the flash directory (flash settings) can be read through the address 0x0000.0024. This is “faked” the same way as the pointer to the hardware info. The address of the flash settings area is hardcoded in the bootloader and can not be altered without changing/replacing the bootloader. For the device specific location, see chapter 8.




8 Device Specifica

8.1 OP 73micro, OP73 micro-debug and OP 73Makefile target: OP73, OP73MICRO and OP73MICRO-debugSupported variants: -Flash usage: 64 kBFlash Sector size: 64 kBSupported Flash Devices: AM29LV160, AM29LV320, AM29DL161, AM29DL162, AM29DL163, AM29DL164 AM29DL322, AM29DL323, AM29DL324, AM29DL640Location of the flash directory: 0x0101.0000Supported Displays: S1D15714, 160x48 @ monoReserved RAM area: 0x0000.0000 – 0x0003.FFFF (256 kB)Transfer Methods: serial transfer via RS485OS Support: eCosCommand Line: none, R0 is always zero

8.2 OP 77AMakefile target: OP77ASupported variants: -Flash usage: 64 kBFlash Sector size: 64 kBSupported Flash Devices: AM29LV160, AM29LV320, AM29DL161, AM29DL162, AM29DL163, AM29DL164 AM29DL322, AM29DL323, AM29DL324, AM29DL640Location of the flash directory: 0x0101.0000Supported Displays: S1D15714, 160x64 @ monoReserved RAM area: 0x0000.0000 – 0x0003.FFFF (256 kB)Transfer Methods: serial transfer via RS485OS Support: eCos and µCLinuxCommand Line: R0 = pointer to string with MTD settings, see section




8.3 HT2Makefile target: HT2Supported variants: -Flash usage: 256 kBFlash Sector size: 64 kBSupported Flash Devices: S29GL016A R2 Location of the flash directory: 0x3008.0000Supported Displays: S6B0724, 128x64 @ mono, using a 6x8 pixel FontReserved RAM area: 0x0000.0000 – 0x003F.FFFF (4 MB)Transfer Methods: ethernet transfer via TFTP (+ HT2 specific DHCP)OS Support: eCosCommand Line: none, R0 is always zero

Note #1: This bootloader does not initialize the hardware, instead it uses the hardware setup that is done by the BIOS.Note #2: The bootloader binary has a CE image header.Note #3: The bootloader uses a self-extractor stub to unpack itself into RAM.Note #4: The DHCP implementation has SIEMENS/MC specific extensions.

8.4 TP 177 familyMakefile target: TP177 (for all variants)Supported variants: TP 177micro, TP 177 and K-TP 178microFlash usage: 64 kBFlash Sector size: 64 kBSupported Flash Devices: AM29DL163, AM29DL323Location of the flash directory: 0x0010.0000Supported Displays: 6” STN, 320x240 @ 2bppReserved RAM area: 0x0C00.0000 – 0x0C03.FFFF (256 kB)Transfer Methods: serial transfer via RS485OS Support: µCLinuxCommand Line: R0 = pointer to string with MTD settings, see section plus

for TP 177-micro: clk=62840901 video=s3c44b0xfb:320:240:2 and K-TP 178micro root=/dev/mtdblock3 touchcal=320,240,75,955,955,75 console=/dev/ttyS1 init=/bin/smart

for TP 177: clk=60750000 video=s3c44b0xfb:320:240:2 root=/dev/mtdblock3 touchcal=320,240,75,955,955,75 console=/dev/ttyS1 init=/bin/smart




8.5 KTP1000 Basic / TP1500 Basic familyMakefile target: XP179 (for all variants)Supported variants: all combinations of: KTP1000 Basic and TP1500 Basic, PN/DP/PN&DP, with/without keyboard, beeper/buzzerFlash usage: 256 kBFlash Sector size: 128 kBSupported Flash Devices: S29GL256NLocation of the flash directory: 0x8004.0000Supported Displays: 10” STN, 320x240 @ 8bpp via S3C2410X builtin

15” STN, 640x480 @ 8bpp via SM502Reserved RAM area: 0x0000.0000 – 0x000F.FFFF (1 MB)Transfer Methods: serial transfer via RS485 + ethernet TransferOS Support: LinuxCommand Line: R0 = 0 R1 = 1290 (architecture) in memory at 0x0010.0100: tag list for Linux Kernel v2.6, tags: - core - memory - command line: “noinitrd init=linuxrc root=/dev/mtdblock3 console=null “ + MTD partitioning - end tag

MMU setup: 0x0000.0000 – 0x03FF.FFFF - SDRAM 0x0800.0000 – 0x0FFF.FFFF - ASPC2 0x1000.0000 – 0x17FF.FFFF - CS_MPUF 0x2000.0000 – 0x27FF.FFFF - ethernet / debug board 0x2800.0000 – 0x29FF.FFFF - ethernet / on board 0x3800.0000 – 0x39FF.FFFF - SM502 0x4000.0000 – 0x4000.0FFF - internal SRAM

0x4800.0000 – 0x5FFF.FFFF - SFR 0x8000.0000 – 0x81FF.FFFF - Flash




8.6 KTP400 Basic / KTP600 Basic familyMakefile target: MAP1 (for all variants)Supported variants:

KTP400 Basic mono PN, with 4” STN KTP400 Basic mono PN, with 4” TFT (not implemented) KTP600 Basic color PN, with 6” STN KTP600 Basic color DP, with 6” STN (not implemented) KTP600 Basic color PN, with 6” TFT KTP600 Basic color DP, with 6” TFT

Flash usage: 256 kBFlash Sector size: 64 kBSupported Flash Devices: AM29LV640, AM29LV641, S29GL064N, S29GL256NLocation of the flash directory: 0x1004.0000Supported Displays:

4” STN, 320x240 @ 4bpp 4” TFT, 320x240 @ 4bpp (not implemented) 6” STN, 320x240 @ 8bpp 6” TFT, 320x240 @ 8bpp

Reserved RAM area: 0x2000.0000 – 0x200F.FFFF (1 MB)Transfer Methods: serial transfer via RS485 and ethernet transferOS Support: ADONISCommand Line: R0 = pointer to zero terminated ASCII string

template: clk=<clock frequency in Hz> ram=0x<size_hex>@<address_hex> flash=0x<size_hex>@<address_hex>

touchcal=<xres>,<yres>,<x_left>,<x_right>,<y_top>,<y_bottom> video=<mono|color>:<xres>:<yres>:<bpp> mac0=xx:xx:xx:xx:xx:xx pn=[0|1] dp=[0|1] contrast=<min>,<max>,<default> device_variant=<dwOP_Sub_hex_from_HWI>

for all variants: clk=75000000 ram=0x00800000@0x20000000 flash=0x01000000@0x10000000 touchcal=320,240,70,935,950,75 device_variant=0x????????

contrast=0,100,50

for PN variants only: mac0=xx:xx:xx:xx:xx:xx KTP400 Basic mono PN 4” STN: video=mono:320:240:4 pn=1 dp=0 KTP600 Basic mono PN 6” STN: video=mono:320:240:8 pn=1 dp=0KTP600 Basic color PN 6” TFT: video=color:320:240:8 pn=1 dp=0KTP600 Basic color DP 6” TFT: video=color:320:240:8 pn=0 dp=1




9 Examples of typical Image HeadersHere some examples for some typical cases of image headers, which were of interest during the time where this document was written. Of course values for length and CRCs are just “fantasy”.

9.1 Runtime under eCosdwRunAdr = 0x0100.0000dwStoreAdr = 0x0100.0000dwOrgLen = 768000dwCompLen = 768000wOrgChkSum = 0xCAFEwCompChkSum = 0xCAFEdwEntryPoint = 0x0100.0040wImageAttrib = ATTR_INPLACEpNextDesc = 0x0000.0000dwImageAreaSize = 768000dwTypeImage = IMAGE_OS_APP

9.2 Hardware test for TP 177dwRunAdr = 0x0C04.0000dwStoreAdr = 0x0014.0000dwOrgLen = 0x0003.0000dwCompLen = 0x0003.0000wOrgChkSum = 0xFFFFwCompChkSum = 0xFFFFdwEntryPoint = 0x0C04.0040wImageAttrib = ATTR_COPY_RAMpNextDesc = 0x0000.0000dwImageAreaSize = 0x0003.0000dwTypeImage = IMAGE_HWT

9.3 Linux Kernel for OP 77AdwRunAdr = 0x0004.0000dwStoreAdr = 0x0103.0000dwOrgLen = 0x0007.6500dwCompLen = 0x0003.4500wOrgChkSum = 0xCAFEwCompChkSum = 0xAFFEdwEntryPoint = 0x0004.0000wImageAttrib = ATTR_COPY_RAM | ATTR_UNPACKpNextDesc = 0x0000.0000dwImageAreaSize = 0x0003.0000dwTypeImage = IMAGE_OS_APP | IMAGE_OS_SPLIT

here: compressed CRC goes from 0x0103.0040 to 0x0106.44FFuncompressed CRC goes from 0x0004.0000 to 0x000B.64BF !!!

(0x000B.64BF = 0x0004.0000 + 0x0007.6500 – 0x40 – 1)




9.4 Root Filesystem for TP 177dwRunAdr = 0x0C60.0000dwStoreAdr = 0x0008.0000dwOrgLen = 0x0007.8000dwCompLen = 0x0007.8000wOrgChkSum = 0xCAFEwCompChkSum = 0xCAFEdwEntryPoint = 0x0000.0000wImageAttrib = ATTR_COPY_RAMpNextDesc = 0x0000.0000dwImageAreaSize = 0x0007.8000dwTypeImage = IMAGE_NONE | IMAGE_OS_SPLIT

9.5 Configuration data for OP 73, stored in transfer areaImage is stored at Address 0x0103.0000 (“@TRA”)

dwRunAdr = 0x0108.0000dwStoreAdr = 0x0108.0000dwOrgLen = 0x0002.0000dwCompLen = 0x0002.0000wOrgChkSum = 0xCAFEwCompChkSum = 0xCAFEdwEntryPoint = 0x0108.0040wImageAttrib = ATTR_INPLACE | ATTR_UNPACKpNextDesc = 0x0000.0000dwImageAreaSize = 0x0002.0000dwTypeImage = IMAGE_OS_APP




9.6 Abbreviations

nu not usedtbd to be definedOS Operation System

10 Bibliography[1] Hardware-Info Windows-CE, G. Wenger, A&D PT1 D1, 21.10.2002 (?), version 1.5

(german)[2] SmaRT flash services, sympat GmbH


smart spec boot loader

Documents