Memtool 3 – Programmers Guide

File Version 1.1.0 (03.02.2000)

Scripting Interfaces

Memtool 3 is implemented as a COM In-process server. Any client that is able to load COM objects from In-
process servers can use the functions of Memtool 3.

Object Model:

- Memtool Object
- one or more FLASH/OTP-Module Objects
- Target Interface Object

Memtool Object

This is the top level object. It is registred as "SMT.Memtool".

Properties:

TargIntf As Object
The Target Interface Object.

NumOfFlashMods As Long
The number of FLASH/OTP Modules on the target.

NumOfSections As Long
Number of sections in file section list.

Methods:

Init(TargInfoFile As String)
Intitializes the Memtool Object using the given Target Info File. After object creation this
function has to be called before any other.

Cleanup()
It is recommended to call this function before releasing the Memtool Object.

GetFlashModByIndex(Index As Long) As Object

Returns a FLASH/OTP Module by its one based index.

GetFlashModByName(Name As String) As Object

Returns a FLASH/OTP Module Object by its name. The names are defined in the MCU Info
File.

ConnectTarget()
Connect the target system.

DisconnectTarget()
Disconnect the target system.

OpenFile(File As String)
Open a Intel-Hex-File and update the file section list.

GetSectionStartAddr(Index As Long) As Long

Returns the start address of a section within the file section list. The index is one based.
 GetSectionSize(Index As Long) As Long
Returns the size (in bytes) of a section within the file section list. The index is one based.

SelectAllSections()
Select all sections within the file section list.

UnselectAllSections()
Unselect all sections within the file section list.

SelectSection(Index As Long)
Select one section within the file section list. The index is one based.

UnselectSection(Index As Long)
Unselect one section within the file section list. The index is one based.

AddSelectedSections()
Transfer data in selected sections to buffers within the corresponding FLASH/OTP Module
Objects.

FLASH/OTP-Module Object:

Properties:

Name As String
The name of the FLASH/OTP Module as specified in the MCU Info File.

Description As String
The description text of the FLASH/OTP Module as specified in the MCU Info File.

CanChipErase As Long
Is 1 if the FLASH/OTP Module allows erasing the whole memory otherwise it is 0.

CanSectorErase As Long
Is 1 if the FLASH/OTP Module allows erasing of sectors otherwise it is 0.

CanProgram As Long
Is 1 if the FLASH/OTP Module allows programming otherwise it is 0.

CanVerify As Long
Is 1 if the FLASH/OTP Module allows verification otherwise it is 0.

NumOfSections As Long
Number of sections in section list.

NumOfSectors As Long
Number of sectors.

Methods:

EraseChip()
Erase the whole memory of the FLASH Module.

EraseSector(Index As Long)
Erase one sector of the FLASH Module. The index is one based.

ProgramSections()
Write sections from section list into FLASH/OTP Module.

VerifySections()
Compare sections from section list with FLASH/OTP Module contents.
Sample Script

On Error Resume Next

' create and initialize the memtool object

Dim memtool
Set memtool = CreateObject("SMT.Memtool")
Call CheckError()

' load target info file

memtool.Init(".\Targets\gen167CS32F_27_CA.dat")
Call CheckError()

' establish target connection

memtool.ConnectTarget
Call CheckError()
WScript.Echo("Target connected")

' get the flash module

Dim flashmod
Set flashmod=memtool.GetFlashModByIndex(1)
Call CheckError()

' clear all sectors

WScript.Echo("Clear sectors ...")
Dim NumOfSectors
NumOfSectors=flashmod.NumOfSectors
Dim i
For i=1 To NumOfSectors
flashmod.EraseSector(i)
Call CheckError()
Next

' open the hex file and load all sections

memtool.OpenFile ".\Data\TOGLED67.HEX"

' program file

WScript.Echo("Program file ...")
memtool.SelectAllSections
memtool.AddSelectedSections
flashmod.ProgramSections

' cleanup and release all objects

Set flashmod=Nothing
memtool.Cleanup
Set memtool=Nothing
WScript.Echo("finished")

' MsgBox("END")

Sub CheckError()
If Err<>0 Then
WScript.Echo(Err.Description)
MsgBox Err.Description
memtool.Cleanup
WScript.Quit
End If
End Sub
SAB C16x Mini-Monitor

The C16x Mini Monitor is loaded into the internal RAM using the bootstrap loader of the MCU. No additional
external bus initialization is done by the monitor.
The monitor is optimized for minimum size due to the internal RAM limitation.

Memory usage:

FA00h - FA1Fh ... stack

FA20h - FA3Fh ... register bank
FA40h - FA5Fh ... loader, not required after target connected
FC30h - FDFFh ... monitor code

After target connection is established the range FA40h – FC2Fh is available for monitor extensions.

Commands:

The monitor uses the ASC0 to receive commands from the host PC and to exchange data. The ASC0
configuration is done by the bootstrap loader.

Protocol: Host: MCU:

<cmd> à
ß 55h (command acknowledge)
<input> à
ß <output>
ß EAh (command end)

A command is always one byte. If a invalid or not supported command code is received the monitor returns the
'command end' code (EAh).

Write Word:

Write one word into memory. Word access is used.

Command: 82h
Input: address (3 bytes, LSB first)
data (2 bytes, LSB first)
Output: -

Read Word:

Read one word from memory. Word access is used.

Command: 83h
Input: address (3 bytes, LSB first)
Output: data (2 bytes, LSB first)

Write Block:

Receive a number of bytes and write it into memory. Byte accesses are used. A simple checksum is built and
reported back to the host.

Command: 84h
Input: address (3 bytes, LSB first)
length (2 bytes, LSB first)
data (<length> bytes)
Output: checksum (2 bytes, LSB first)
Read Block:

Read a number of bytes and send it to the host. Byte accesses are used. A simple checksum is built and reported
back to the host.

Command: 85h
Input: address (3 bytes, LSB first)
length (2 bytes, LSB first)
Output: data (<length> bytes)
checksum (2 bytes, LSB first)

Execute Monitor Extension:

A application located somewhere in the memory is 'called'. Up to 8 word parameters are passed in and reported
back through registers R8-R15. The application has to do a 'RETS' to return to monitor.
NOTE: Only 14 words of stack space are available !!!

Command: 9Fh
Input: R8-R15 (8 words, LSB first)
Output: R8-R15 (8 words, LSB first)

Execute Special Command:

A special MCU instruction like EINIT is executed. The Instruction to execute is specified by an additional sub
command.

Command: 9Dh
Input: sub cmd code (1 byte)
Output: -

Sub commands: EINIT code: 31h

SWRESET code: 32h
Target Information Files

A Target Information File contains all informations about a target system that Memtool requires to connect to
this target. It is a ASCII file in Windows INI-File format and can be modified using a text editor.
Use a separate Target Information File for each target system.

Section 'Main'

Entry 'Name':
short target name, up to 32 chars, required

Entry 'Description':
target description text, up to 256 chars, optional

Entry 'MCUType':
type of the target controller, up to 32 chars, required If no 'MCUInfoFile' entry is set
'.\Types\<MCUType>\<MCUStep>\<MCUType>.dat' is assumed as default path of the MCU Info File.
If not found or 'MCUStep' is not set '.\Types\<MCUType>\<MCUType>.dat' is assumed.

Entry 'MCUStep':
additional step information of target controller, up to 32 chars, optional
If set '.\Types\<MCUType>\<MCUStep>\<device name>.dat' is assumed as default path of the Memory
Device Driver File.
If not set '.\Types\<MCUType>\<device name>.dat' is assumed as default path of the Memory
Device Driver File.

Entry 'MCUInfoFile':
path of the MCU Info File, optional
If not set '.\Types\<MCUType>\<MCUType>.dat' is assumed as default path of the MCU Info File.

Entry ' IntMCUClock ':

internal MCU clock frequency (kHz), optional
If not set 20000 kHz are assumed.

Entry 'InitCmd0...n':
additional initialization commands that are executed when connecting the target

Initialization Commands

EINIT:
Execute the 'EINIT' instruction.

SWRESET:
Execute the 'SWRESET' instruction.

SET <regname>|<regaddr> <value> [<mask>]:

Write a word value into memory, the destination address may be specified as a register name or
numeric value, if a mask value is specified a target bit is touched only if the corresponding bit within
mask is set to one, a register name must be resolved to a numeric address within the MCU Info File.

Each numeric value is assumed as decimal by default. Use '<value>h' or '0x<value>' for hexadecimal values.

Additional other components write target specific settings into the Target Information File. These sections
should not be modified by the user.
Example for ertec Eva167 with SAB C167CS-32FM and external memory usage

[Main]
Name=EVA167CS
Description=ertec EVA167 with SAB C167CS-32F
MCUType=C167CS-32F
InitCmd0=SET SYSCON 1484h
InitCmd1=SET BUSCON0 49Eh
InitCmd2=SET BUSCON1 49Eh
InitCmd3=SET ADDRSEL1 6h
InitCmd4=EINIT
MCU Info File

A MCU Information File contains all informations about a target controller that Memtool requires to handle its
on-chip FLASH/OTP memory devices. It is a ASCII file in Windows INI-File format and can be modified using
a text editor.

Search order:

If an entry 'MCUInfoFile' is set in the Target Info File the value of this entry is used as path of the MCU Info
File. Otherwise the the path is built from the entries 'MCUType' and (optional) 'MCUStep'.
If 'MCUStep' is set the following location and file name is assumed :

<memtool install dir>\Types\<MCUType>\<MCUStep>\<MCUStep>.dat

If this file doesn't exist or 'MCUStep' is not set the following location and file name is assumed :

<memtool install dir>\Types\<MCUType>\<MCUType>.dat

Section 'Main'

Entry 'Name':
controller type, up to 32 chars, required

Entry 'Description':
controller description text, up to 256 chars, optional

Entry 'AckCode':
bootstrap loader acknowledge code, more then one value may be specified, use commas to separate

Entry 'MemDev0...':
names of on-chip memory devices, up to 32 chars, a section within this as section name is expected to
hold additional information about the memory device

Section '<device name>' (one section for each on-chip memory device is expected)

Entry 'Description':
memory device description text, up to 256 chars, optional

Entry 'Handler':
If this is set to 'MEMTOOL' the Memtool handles this memory device.

Entry 'Driver':
path of device driver file, optional
If not set '.\Types\<MCUType>\<device name>.dat' is assumed as default path of the driver file.
If the entry 'MCUStep' is set in the Target Information File '.\Types\<MCUType>\<MCUStep>\
<device name>.dat' is assumed as default path of the driver file.

Entry 'DrvStart':
start address of the driver, optional
If not set the start address is taken from the driver file.

Entry 'PasswordSize':
If a protection password is supported by the memory device this specifies the size of the password in
words.

Entry 'Message_<return code>':

If the driver uses a non standard return code a corresponding text message may be placed here.
<return code> is always a 4 digit hexadecimal number. optional
 Entry 'IgnoreError':
List of driver error return values for which no error message should be displayed. The numeric values
are separated by ',' or spaces. optional

Entry 'NumOfSectors':
number of sectors the memory device has, required

For each sector X some entries are required (X ... zero based decimal index) :

Entry 'SectorXNumOfBlocks':
number of ranges the sector has, optional, default 1

For each range Y of sector X some entries are required (Y ... zero based decimal index):

Entry 'SectorXBlockYSize':
range size in bytes, required

Entry 'SectorXBlockYStartAddr':
range start address with ROMS1 not set, required

Entry 'SectorXBlockYRemapStart':
range start address with ROMS1 set, optional, default equal to value of 'SectorXBlockYStartAddr'

To display FLASH/OTP device status informations a description for each bit within a status register may be
specified:

Entry 'State_<bit number>':

<bit number> is the 2 digit, zero based, hexadecimal index of the bit
The entry contains a comma separated list of the following form:
<bit name>,<bit description>,<message, if bit is 0>,<message, if bit is 1>.

Section 'RegAddr':

To allow the usage of symbolic names instead of numeric addresses two lists of address name pairs are provided.

Entry 'RegAddr_<numeric value>':

assigns a symbolic name with the numeric address value

Entry 'RegAddr_<symbolic name>':

assigns a numeric address value with the symbolic name

Each numeric value is assumed as decimal by default. Use '<value>h' or '0x<value>' for hexadecimal values.
FLASH/OTP Device Drivers

The FLASH/OTP Module Drivers are implemented as Monitor Extensions for C16x Mini-Monitor. 8 word
parameters (WP0-WP7) are passed in and returned through R8-R15. Additionally the driver has a default
transfer buffer to exchange data with the host. Each driver implements a set of sub functions which are selected
by the first parameter. The following Sub Function Codes are defined :

FLDRV_CMD_INIT code: 0
FLDRV_CMD_CHIPERASE code: 1
FLDRV_CMD_SECTORERASE code: 2
FLDRV_CMD_PROGRAM code: 3
FLDRV_CMD_VERIFY code: 4
FLDRV_CMD_QUERYSTATE code. 5
FLDRV_CMD_CHIPPROT code: 6
FLDRV_CMD_SECTORPROT code: 7
FLDRV_CMD_PASSWORD code: 8
FLDRV_CMD_GETTYPE code: 9

Each sub function reports back an error output value through WP7 (R15). The following Error Return Codes
are defined :

FLDRV_S_NOERROR 0000h ... function succeeded

FLDRV_E_FAILED 8001h ... FLASH/OTP operation failed
FLDRV_E_UNKCMD 8002h ... unknown or not implemented
Sub Function Code
FLDRV_E_MODDISABLED 8003h ... FLASH/OTP module disabled
FLDRV_E_IVMAPPING 8004h ... invalid mapping variant
FLDRV_E_NOVPP 8005h ... programming voltage not on
FLDRV_E_IVPROGVPP 8006h ... invalid Programming voltage
FLDRV_E_MAXPROGPULSEEX 8007h ... max. number of program pulses exceeded
FLDRV_E_IVSECTOR 8008h ... invalid sector index
FLDRV_E_MAXERASEPULSEEX 8009h ... max. number of erase pulses exceeded
FLDRV_E_ERASETIMEOUT 800Ah ... timeout waiting for erase finished

To tell the host what functions are supported by the driver it reports some capability flags within the return
parameter WP4 of the 'Driver Init' sub function:

FLDRV_CAP_CHIPERASE 0001h ... chip erase supported

FLDRV_CAP_SECERASE 0002h ... sector erase supported
FLDRV_CAP_PROGRAM 0004h ... programming supported
FLDRV_CAP_VERIFY 0008h ... has special (non read) verify function
FLDRV_CAP_READ 0010h ... direct read accesses supported
FLDRV_CAP_QUERYSTATE 0020h ... state informations supported
FLDRV_CAP_CHIPPROT 0040h ... chip protection supported
FLDRV_CAP_SECPROT 0080h ... sector protection supported
FLDRV_CAP_PASSWORD 0100h ... password function supported
FLDRV_CAP_ALTTRBUF 0200h ... driver can use an alternative transfer buffer
Sub Function 'Driver Init'

Each time the driver is downloaded this function is called first. Do all initialisations here.

IN: INP_CMD (WP0)= FLDRV_CMD_INIT

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)
INIT_INP_CLOCK (WP2): internal MCU clock (kHz)

OUT: INIT_OUT_TRBSIZE (WP0): default transfer buffer size (bursts)

INIT_OUT_TRBSTARTH (WP1): default transfer buffer start address high (SEG)
INIT_OUT_TRBSTARTL (WP2): default transfer buffer start address low (SOF)
INIT_OUT_FB_BS (WP3): low byte: fill byte, high byte: burst size (bytes)
INIT_OUT_CAPS (WP4): FLASH module/FLASH driver capability flags
INIT_OUT_CAPS2 (WP5): (not used currently)
INIT_OUT_CFG (WP6): current FLASH module configuration
OUT_ERROR (WP7): return code
transfer buffer (W0): expected password size if FLDRV_CAP_PASSWORD is set

Sub Function 'Chip Erase'

Erase the whole FLASH module.

IN: INP_CMD (WP0)= FLDRV_CMD_CHIPERASE

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)

OUT: OUT_ERROR (WP7): return code

Sub Function 'Sector Erase'

Erase one sector of the FLASH module.

IN: INP_CMD (WP0)= FLDRV_CMD_SECERASE

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)
INP_STARTH (WP2): FLASH sector start address high (SEG)
INP_STARTL (WP3): FLASH sector start addrees low (SOF)
SECERASE_INP_INDEX (WP4): FLASH sector index

OUT: OUT_ERROR (WP7): return code

Sub Function 'Program'

Write one or more bursts into the FLASH module. If FLDRV_CAP_ALTTRBUF is set WP5/6 hold the actual
transfer buffer location.

IN: INP_CMD (WP0)= FLDRV_CMD_PROG

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)
INP_STARTH (WP2): FLASH destination address high (SEG)
INP_STARTL (WP3): FLASH destination address low (SOF)
PROG_INP_BURSTS (WP4): number of bursts to program
PROG_INP_TRBSTARTH (WP5): transfer buffer start address high (SEG)
PROG_INP_TRBSTARTL (WP6): transfer buffer start address low (SOF)
transfer buffer: data to program

OUT: OUT_ERROR (WP7): return code

Sub Function 'Verify'

Verify one or more bursts of FLASH contents. If FLDRV_CAP_ALTTRBUF is set WP5/6 hold the actual
transfer buffer location. This function is required only if no direct read access is possible.

IN: INP_CMD (WP0)= FLDRV_CMD_VERIFY

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)
INP_STARTH (WP2): FLASH destination address high (SEG)
INP_STARTL (WP3): FLASH destination address low (SOF)
VERIFY_INP_BURSTS (WP4): number of bursts to verify
VERIFY_INP_TRBSTARTH (WP5): transfer buffer start address high (SEG)
VERIFY_INP_TRBSTARTL (WP6): transfer buffer start address low (SOF)
transfer buffer: data to verify

OUT: OUT_ERROR (WP7): return code

Sub Function 'Query State'

Read one or more FLASH module state values. If number of state values is one the value is returned in WP1.
Otherwise all state values are returned in the default transfer buffer.

IN: INP_CMD (WP0)= FLDRV_CMD_QUERYSTATE

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)

OUT: QUERYSTATE_OUT_NUMVALS (WP0): number of state values (words)

QUERYSTATE_OUT_VALUE (WP1): state value
OUT_ERROR (WP7): return code
transfer buffer: state values

Sub Function 'Chip Protection'

Install, check or clear the FLASH module chip protection. If required the password is passed in within the
transfer buffer.

IN: INP_CMD (WP0)= FLDRV_CMD_CHIPPROT

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)
CHIPPROT_INP_CMD (WP2): protection command
CHIPPROT_INP_PWSIZE (WP2): size of password (bytes)
transfer buffer: password for clear command

OUT: CHIPPROT_OUT_STATE (WP0): protection state after function

OUT_ERROR (WP7): return code

Sub Function 'Sector Protection'

Install, check or clear the FLASH module sector protection for one sector. If required the password is passed in
within the transfer buffer.

IN: INP_CMD (WP0)= FLDRV_CMD_SECTORPROT

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)
INP_STARTH (WP2): FLASH sector start address high (SEG)
INP_STARTL (WP3): FLASH sector start addrees low (SOF)
SECPROT_INP_INDEX (WP4): FLASH sector index
SECPROT_INP_CMD (WP5): protection command
SECPROT_INP_PWSIZE (WP6): size of password (bytes)
transfer buffer: password for clear command

OUT: SECPROT_OUT_STATE (WP0): protection state after function

OUT_ERROR (WP7): return code
Sub Function 'Password'

Read or write a password into FLASH module.

IN: INP_CMD (WP0)= FLDRV_CMD_PASSWORD

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)
PASSWORD_INP_CMD (WP2): password command
PASSWORD_INP_SIZE (WP3): password size
transfer buffer: password to write

OUT: OUT_ERROR (WP7): return code

transfer buffer: password read

Sub Function 'GetType'

Query the type of external FLASH modules.

IN: INP_CMD (WP0)= FLDRV_CMD_GETTYPE

INP_FLASHSTARTH (WP1): FLASH base address high (SEG)

OUT: GETTYPE_OUT_VID_EVEN (WP0): vendor ID even bank

GETTYPE_OUT_CID_EVEN (WP1): chip ID even bank
GETTYPE_OUT_VID_ODD (WP2): vendor ID odd bank
GETTYPE_OUT_CID_ODD (WP3): chip ID odd bank
OUT_ERROR (WP7): return code