Adding a module to the Total Phase Flash Center software

TotalPhase

1. Introduction

Although by default many memory devices are included in the Flash Centre parts list, users may find that the part they wish to program is not present. Therefore, the Flash Centre includes a method for users to add additional memory parts to the library and specify the parameters for programming those parts. To add a memory device to Flash Center, the user must first define the programming parameters for memory parts in an XML file and then load the file into Flash Center.

2. Importing storage device files

There are two ways to add storage devices from a storage device file to the Flash Centre parts list.

One method of loading the file into the Flash Centre is to open the Select Target Device dialogue box and then click the Load Part File ... button. The memory part file can then be selected in the file selection dialogue.

The other way to add the parts defined in a memory parts file is to store the file in the parts directory of the flash centre. This directory is located in the installation directory of the Flash Center and is called Parts. When the Flash Centre is started, all files that have the file extension .xml are automatically loaded into the parts directory.

Regardless of the method chosen to load the memory parts file, if properly formatted, the parts will be integrated into the parts list and can be selected for programming in the Select Target Device dialogue box.

Note: The device usage parameters for the storage devices must be unique. If the device name parameters are duplicated between part definitions, later loaded parts will overwrite earlier loaded part definitions. This is useful when using the "Load Part File..." option as it allows the part definitions to be refined without having to restart Flash Center. If the parts with duplicate parameters for the device name are in the parts directory, it is undetermined which ones will be loaded.

3. Defining storage device files

To add a storage device to the Flash Centers parts list, the part must first be defined in a storage device file.

To use a higher bit rate than the maximum bit rate specified in the parts library with Promira Serial Platform, a file must be updated in the parts directory.

The maximum SPI bit rate with the Promira Serial Platform with SPI Active Level 3 application is 80 MHz.
Check the memory part datasheet to ensure that the memory part supports the desired bit rate.
open the file in the parts directory that specifies the desired memory part.
Update maxBitrate to the desired bit rate. Make sure this bitrate is equal to or less than the maximum bitrate of your Promira Serial Platform.
Not recommended to update other nodes.
The following example shows a memory part file from one of the files included with the Flash Centre: st-spi-flash-m25pe.xml. It defines 4 memory parts that inherit most of their parameters from the global default values or the default values declared at the top of the file.

<?xml version="1.0" binding="UTF-8"?> <devices> <default version="1.0"><manufacturerName> STMicro </manufacturerName> <deviceAlgorithm>SPI flash</deviceAlgorithm> <maxBitrate>33000</maxBitrate> <addressWidth>3</addressWidth> <readDummyBytes>1</readDummyBytes> <writeSize>256</ writeSize> <eraseSize>256</eraseSize> <writeTime>1200</writeTime> <eraseTime>10000</eraseTime> <readInstruction>0x0b</readInstruction> <readDeviceIdInstruction>0x9f</readDeviceIdInstruction> <eraseInstruction>0xdb</eraseInstruction> <deviceConnectedBits>0x00</deviceConnectedBits><deviceConnectedMask>0xfc</deviceConnectedMask> </default> <device version="1.0"> <deviceName>M25PE10</deviceName> <deviceDescription> STMicro M25PE10 128 Kilobyte SPI Flash </deviceDescription> <capacity>128*1024</capacity> <expectedDeviceId></expectedDeviceId> <device version> <device version="1.0"> <deviceName>M25PE20</deviceName> <deviceDescription> STMicro M25PE20 256 Kilobyte SPI Flash </deviceDescription> <capacity>256*1024</capacity> <expectedDeviceId>\\x20\x80\x12</expectedDeviceId> </device> <device version="1.0"> <deviceName>M25PE40</deviceName> <deviceDescription> STMicro M25PE40 512 Kilobyte SPI Flash </deviceDescription> <capacity>512*1024</capacity> <expectedDeviceId>\\x20\ \x80\x13</expectedDeviceId> </device> <device version="1.0"> <deviceName>M25PE80</deviceName> <deviceDescription> STMicro M25PE80 1 Megabyte SPI Flash </deviceDescription> <capacity>1024*1024</capacity> <maxBitrate>50000</maxBitrate> <hasEraseAll>true</hasEraseAll> <writeTime>1350</writeTime> <eraseAllTime>10*1000000</eraseAllTime> <eraseAllInstruction>0xc7</eraseAllInstruction> <expectedDeviceId>\\x20\\x80\x14</expectedDeviceId> </device> <device version="1.0"> <deviceName>M25PE16</deviceName> <deviceDescription> STMicro M25PE16 2 Megabyte SPI Flash </deviceDescription> <capacity>2*1024*1024</capacity> <maxBitrate>50*1000</maxBitrate> <blockProtectBits>0x1c </blockProtectBits> <hasEraseAll>true</hasEraseAll> <writeTime>800</writeTime> <eraseAllTime>17*1000000</eraseAllTime> <eraseAllInstruction>0xc7</eraseAllInstruction> <expectedDeviceId>\\x20\x80\x15</expectedDeviceId> <deviceConnectedMask>0x60</deviceConnectedMask> </device> </devices>

3.1. memory file part format

The part definition format used for the Flash Centre is based on XML. (For an overview of the XML format, see the official XML website at http://www.w3.org/XML/.)

The memory part file format contains several elements. It starts with the XML declaration and is followed by the <devices> node, which may contain a <default> node and several <device> nodes. The <default> node and the <device> node each contain several elements that define parameter values for storage devices. Each <device> node defines a single storage device. The <Standard> node can be used to define common characteristics of all storage devices in the file.

XML declaration

The first line in the sample file is the XML declaration line. This line should be the first line in all storage part files.

Device node

The only root-level element in the XML file is the <devices> element node. All other elements in the file are child nodes of the <devices> node. The second line of the file should be the declaration of the <devices> node, and the last line of the file should close the <devices> node. The <default> node and all <device> nodes should be child nodes of the <devices> node.

Default node

The <default> node is an optional node that defines the common parameter values for all devices defined in the file. Any parameters defined in the <default> node will override the built-in default values for that single parameter.

The <default> element has one attribute, version, which must be set to 1.0. There should be only one <default> node. If there is more than one <default> node, only the first one will be analysed. the rest will be ignored.

Device nodes

Each <device> node in the memory file defines a single memory part. Multiple <device> nodes are allowed under the <device> node, each defining a different memory device. The parameter values declared under each <device> node define the characteristics of the device and also identify the programming method for the memory device. The parameters defined in each <device> node vary depending on the type of storage device and the specifics of the storage device.

When adding new parts to the Flash Centre parts list, it is important that the new part has a unique name as defined in the <device name> parameter. If there are storage parts that have the same <deviceName> value, only one of the parts will be added to the parts list. In this situation, a warning is displayed to the user.

The <device> element has an attribute, version, which must be set to 1.0.

DualIO node and QuadIO node

The <dualIO> node and the <quadIO> node, which are allowed under the <device> node, define the dual E / A and quad E / A modes for the storage device. If Dual or Quad is selected for SPI I/O mode, the parameters under the <dualIO> or <quadIO> node are used. All parameters not defined under these nodes are inherited from the <device> node

3.2 Device parameters

In the memory part file, each memory device is described as a list of parameter values that define features such as the name of the device, the size of the memory, the type of device, etc. The parameters required to define a particular memory part This depends on the type of memory as well as other specific characteristics of the part.

Note: Parameter names are case sensitive.

Default parameter values

Default values are defined for some parameters, so they do not need to be defined for most storage devices. For example, baseDeviceAddress and writeInstruction have default values of 0x50 and 0x02 respectively. These default values are taken from typical values for these parameters. For many memory parts, the default values are correct, so these parameters do not need to be defined in the <device> node. For those parts whose parameter values differ from the default values, specifying this parameter overrides the default value.

In addition, file-specific default parameter values can be defined by defining the parameter value in the <default> node. The parameters defined under the <default> node override the regular default values. As with the regular default values, the file-specific default settings can also be overwritten in the <device> node for each individual memory part.

Parameter types

There are four main types of device parameters: text, Boolean, integer and binary. In addition, there is one parameter, deviceAlgorithm, a text type parameter for which only three specific values are accepted.

The "text" parameters can accept any text input. Examples are ManufacturerName and deviceDescription, where any XML-allowed string value is acceptable.

The "Boolean" parameters allow two values: true or false, case-insensitive. Examples of Boolean parameters are hasEraseAll and BusyBitPolarity.

The "Integer" parameters take unsigned numeric values. By default, integer values are analysed as decimal values. If you prefix the value with 0x, the Flash Centre analyses the value as a hexadecimal value. In addition, integer values can be defined as multiplication of two values with the * symbol. (No spaces are allowed around the * symbol.) For example, 16384, 0x4000, 16 * 1024, 0x10 * 0x400 and 0x10 * 1024 represent the same value. Examples of integer parameters are capacity, writeInstruction and deviceBusyBit.

The "binary data" parameters represent a sequence of byte values. Each byte value in the sequence can be represented by any XML-permitted character or entered as a hexadecimal value with the prefix \ x. For example, abc123, \ x20 \ x80 \ x14 and abc \ xff are valid entries for a binary data value.

Memory device types

There are three types of storage devices supported by the Flash Centre. These are: I2C EEPROM, SPI EEPROM and SPI Flash. Some memory device parameters are common to all three memory device types, while some are specific to I2C EEPROMs, some are specific to SPI devices (both EEPROMs and Flash devices) and some parameters are specific to SPI Flash devices.

3.3 Global Storage Device Parameters

The following is a table of parameters common to all storage devices. All of these parameters must be defined for each storage unit.

Parameter	Type	Default	Description
`deviceAlgorithm`	text		The type of memory device. The programming algorithm is determined based on this parameter value. Supported values are i2c eeprom, spi eeprom and spi flash, which are case insensitive.
`deviceName`	text		The name of the storage device. Note that the device name must be unique; devices with duplicate names will result in an error.
`deviceDescription`	text		A long description of the device. Displayed when the storage device is selected during destination selection. Normally it includes the manufacturer name, device name, memory size and device type.
`manufacturerName`	text		The manufacturer of the storage device.
`capacity`	int		Size of the device in bytes. The value must not be zero.
`maxBitrate`	int		The maximum bit rate the unit can use to communicate with the programming adapter. The value must not be zero. If there are multiple speed levels for the memory part, the highest bit rate is recommended for this parameter.
`addressWidth`	int	`1`	The number of bytes in the memory address field when reading from and writing to the device. If the address has overflow bits, they are automatically added to the device address (I2C) or command code (SPI). The value must not be zero.
`writeSize`	int		The number of bytes per write. For parts with variable page sizes, enter the size of the smallest page. The value must not be zero.
`writeTime`	int		The number of microseconds required to complete a write operation on a single page. Use the minimum or typical value as the Flash Centre may poll the device to wait additional time if needed. If there are multiple speed levels for the storage portion, the lowest time is recommended for this parameter. The value must not be zero.

3.4 I2C Memory Device Parameters

The following is a table of parameters specific to I2C EEPROM memory devices.

Parameter	Type	Default	Description
`baseDeviceAddress`	int	`0x50`	The base device address for I 2 C devices.
`pageShift`	int	`0`	Devices whose capacity exceeds the total number of bits provided in their address word use bits of the I 2 C -device address to fully address the data. The parameter `pageShift` specifies the position of the least significant bit of these address bits in the I 2 C -device address. This parameter is normally zero, but the Microchip 24xx1025 family is one that requires this parameter.
`autoPageUpdate`	bool	`TRUE`	Devices whose capacity exceeds the total number of bits provided in their address word use bits of the I 2 C device address to fully address the data. The parameter `autoPageUpdate` specifies whether the device's internal address counter can automatically exceed page limits so that these bits do not need to be changed during a sequential read. This parameter is always `false,` if `pageShift` is not zero.

3.5 Required SPI Memory Device Parameters

The following is a table of required parameters specific to both SPI EEPROM devices and SPI Flash devices. All of these parameters must be defined for all SPI memory devices. However, for many of these parameters the default values are the correct values

Parameter	Type	Default	Description
`readStatusRegisterInstruction`	int	`0x05`	The instruction to read the device status register. This is the register containing the busy bit and the block protection bits. This must be set to enable polling.
`deviceBusyBit`	int	`0x01`	The bits in the status register indicating that an operation is being performed. This parameter is used as a bit mask in the status register to determine the busy status. This must be set to enable polling.
`BusyBitPolarity`	bool	`FALSE`	The polarity of the busy bit in the status register. Set to`true` , if the busy bit has a reversed polarity, which means 1 ready.
`readInstruction`	int	`0x03`	The instruction that initiates a read operation from the device. For devices with a fast read instruction, the default value should be overwritten.
`readDummyBytes`	int	`0`	The number of fill bytes to insert between the `readInstruction` and moving data out of the device. Normally, this parameter only needs to be set for flash devices with a fast read command.
`writeInstruction`	int	`0x02`	The instruction to write data to the device.
`writeEnableInstruction`	int	`0x06`	The instruction sent to enable writing to the device. Set to 0 if the device has no write enable instruction.
`writeDisableInstruction`	int	`0x04`	The instruction sent to exit write mode. Set to 0 if the device does not have a write disable instruction.
`writeEnableBits`	int	`0x02`	The bits of the status register that indicate successful execution of the `writeEnableInstruction` .

3.6 Optional SPI Memory Device Parameters

The following is a table of optional parameters specific to both SPI EEPROM devices and SPI Flash devices. Although these parameters are not required, their definition improves the Flash Centre's ability to detect errors during the programming process.

Parameters	Type	Default	Description
`readDeviceIdInstruction`	int		For devices that support this, the instruction to read the device ID.
`expected device ID`	Binary data _		The ID code expected from the instruction to read the device ID. The definition of this parameter is only necessary if also `readDeviceIdInstruction` is defined.
`advancedAddressingEnableInstruction`	int		For large memory devices with backward compatible read, program and erase operations, this instruction enables the advanced addressing mode for these backward compatible operations. For devices with new extended read-only, programming and erase instructions, specify these instructions instead of this command.
`writeBufferInstruction`	int		For memory devices that have a two-part page programming process, this defines the instruction to write data to a memory buffer. For examples of memory parts that use memory buffers for page programming, see the Atmel AT45DBxxxx family of SPI Flash devices.
`writeAutoAddressIncrementInstruction`	int		For SST memory devices that have an Auto Address Increment (AAI) program process, this defines the AAI program instruction.
`writeAutoAddressIncrementSize`	int		For SST storage devices that have an Auto Address Increment (AAI) program process, this defines the number of bytes that follow each instance of the AAI instruction. The value must be non-zero if the AAI program instruction is defined.
`writeAutoAddressIncrementTime`	int		For SST storage devices that have an Auto Address Increment (AAI) program process, this defines the number of microseconds required to complete each AAI write iteration. Unlike `writeTime` this value should be the maximum write time, not the minimum. The value must be non-zero if the AAI program instruction is defined.
`writeStatusRegisterInstruction`	int	`0x01`	The instruction to write to the status register. Set to 0 if the device has no instruction to write the status register.
`writeStatusRegisterEnableInstruction`	int		The instruction to enable writing to the status register. Define this parameter for parts that have separate instructions for write enable and write status register enable. If this parameter is not defined, the flash centre uses the instruction defined for `writeEnableInstruction` is used.
`writeStatusRegisterTime`	int	`5000`	The number of microseconds required to complete a write to the status register. Use the minimum or typical value, as the Flash Centre may poll the device to wait additional time if needed. If there are multiple speed levels for the memory portion, the lowest time is recommended for this parameter.
`deviceConnectedBits`	int		The bits of the status register that are always set to 1 . This is set with the parameter `"deviceConnectedMask"` to detect unconnected SPI devices. For more information on this parameter, see the following section.
`deviceConnectedMask`	int		The bits of the status register that have a fixed value. This is used with the parameter `"deviceConnectedBits"` to detect unconnected SPI devices. If not defined, the value of `deviceConnectedBits is used.` For more information on this parameter, see the following section.
`blockProtectBits`	int	`0x9c`	Determines which bits of the status register indicate that the device blocks or the status register are write-protected. For more information on this parameter, see the following section.
`Sleep mode`	int	`0`	Sets the SPI mode (0-3). 0 : Mode 0. Data is captured on the rising edge of the clock (transition from low to high) and data is passed on a falling edge (transition from high to low). 1 : Mode 1. Data is captured on the falling edge of the clock and passed on a rising edge. 2 mode 2: Data is captured on the falling edge of the clock and passed on a rising edge. 3 : Mode 3: Data is captured on the rising edge of the clock and passed on a falling edge.
`spiBitorder`	bool	`TRUE`	Sets the SPI bit order. The bitorder option is used to specify whether LSB or MSB is shifted first. Set to true for MSB.
`spiSSPolarity`	bool	`TRUE`	Sets the SS polarity, i.e. the output polarity on the SS line. Set to "true" for active low.

Device Connected Bits and Mask

In the SPI protocol, there is no predefined method for an SPI slave device to acknowledge receipt of commands from the SPI master. Therefore, the SPI master could send a command to the slave, but the master may not have a method for determining whether a slave device has been connected to receive it. However, if an SPI memory device has bits in the status register that always have a fixed value, Flash Center's status register can be used to determine whether or not there is a connection to the device.

The deviceConnectedBits and deviceConnectedMask parameters are used to define these bits in the status register. The deviceConnectedMask parameter tells Flash Center which bits have a fixed value, and deviceConnectedBits specifies how high the value of these bits is. When these parameters are defined for a storage device, Flash Center checks these bits for a connection to the target device both while the storage device is idle and while a storage operation, such as a page program or sector erase operation, is in progress .

If deviceConnectedBits is defined but deviceConnectedMask is undefined or 0, Flash Center uses the value of deviceConnectedBits for deviceConnectedMask. This results in Flash Center only being able to detect bits in the status register that have a fixed value of 1, but not bits that have a fixed value of 0.

If both deviceConnectedBits and deviceConnectedMask are undefined or 0, the status register will not be used to detect a connection to the target storage device.

Note: Some memory devices return different results when the status register is read during a memory operation. For example, the Atmel AT25xxxx family returns b1111_1111 while a memory operation is in progress. Since none of the bits in the status register have the same value while the parts are inactive, deviceConnectedBits and deviceConnectedMask are not defined for these parts, and the status register is not used to determine a connection to the parts.

Block protection bits

Most SPI memory parts have a system to protect parts of the memory from changes. The blockProtectBits parameter tells Flash Center which bits of the status register indicate that block protection is enabled. Typically, a storage device has a bit in the status register to indicate that block protection is enabled, as well as bits to indicate which blocks are protected. All these bits should be contained in the blockProtectBits parameter.

If any of the block protection bits in the status register is non-zero at the start of an erase or write operation, the flash centre will write 0 to the status register to erase the block protection. If the status register write command is not defined or writing to the status register does not clear the block protection bits, an error message is displayed and the operation is terminated.

For units whose block protection bits are not cleared by writing to the status register (e.g. they have special instructions to clear the block protection), the block protection must be cleared before Flash Centre is used to programme the unit.

3.7 User Definable SPI Memory Device Parameters

The following is a table of optional user-definable parameters available for both SPI EEPROM devices and SPI Flash devices. Two user transaction fields allow users to define any SPI transaction data that Flash Center sends before each read, write and erase operation.

Parameters	Type	Default	Description
`userTransaction1`	Binary data _		User-definable transaction sent before the start of each read, programming or erase operation.
`userTransaction2`	Binary data _		User-definable transaction sent before the start of each read, programming or erase operation.
`userTransaction1WriteEnable`	bool	`FALSE`	Set`to true` to send the `writeEnableInstruction` before sending `userTransaction1` .
`userTransaction2WriteEnable`	bool	`FALSE`	Set`to true` to send the `writeEnableInstruction` before sending `of userTransaction2` .
`userTransaction1Time`	int		The number of microseconds required to complete `of userTransaction1` . Use the minimum or typical value, as the Flash Centre may poll the device to wait additional time if needed. If there are multiple speed levels for the memory part, the lowest time is recommended for this parameter.
`userTransaction2Time`	int		The number of microseconds required to complete `from userTransaction2` . Use the minimum or typical value, as the Flash Centre may poll the device to wait additional time if needed. If there are multiple speed levels for the storage part, the lowest time is recommended for this parameter.

Notes on user-definable transactions

The bytes specified in the two userTransaction fields are sent unchanged on the SPI bus. The instruction byte and other data should be combined in one userTransaction field. If the provided operation requires a write enable (e.g. register programming), use the write enable boolean fields.

The following example shows programming a non-volatile configuration register with the command 0xB1, the required data 0xFFFF, WREN and the average write time of 0.2 seconds.

 <userTransaction1>\\xB1\xFF\xFF</userTransaction1> <userTransaction1WriteEnable>true</userTransaction1WriteEnable>. <userTransaction1Time>200000</userTransaction1Time>

3.8 SPI Flash Memory Device Parameters

The following is a table of parameters specific to SPI flash memory devices.

Parameter	Type	Default	Description
`Erase instruction`	int		The instruction that erases a portion of the unit. If the unit has multiple erase sizes (for units with sector and block erase), it is recommended to specify the instruction for the smaller erase size.
`EraseSize`	int		The size of the erase instruction specified by `eraseInstruction` in bytes . If the unit has multiple erase sizes (for units with sector erase and block erase), it is recommended to specify the smaller size. The value must not be zero.
`EraseTime`	int		`The number of microseconds required to complete the erase operation specified in eraseInstruction` . Use the minimum or typical value, as the Flash Centre may poll the device to wait additional time if needed. If there are multiple speed levels for the memory part, the lowest time is recommended for this parameter. The value must not be zero.
`hasEraseAll`	bool	`FALSE`	`If` set to `true` , this means that the device supports the chip erase instruction and `eraseAllInstruction` and `eraseAllTime` must be defined.
`EraseAllInstruction`	int		The instruction to perform a complete chip erase operation.
`EraseAllTime`	int		The number of microseconds required to perform the chip erase operation. Use the minimum or typical value, as the Flash Centre may poll the device to wait additional time if needed. If there are multiple speed levels for the memory part, the lowest time is recommended for this parameter. The value must not be zero.
`eraseBeforeWrite`	bool	`TRUE`	If the value is set to `"false`" , Flash Center will not issue erase commands before a write command. This is useful for devices such as the Atmel AT45DBxxxx family of SPI Flash devices, as they support a single command that erases and programs a memory page.

3.9 SPI I/O Mode Parameters

The following is a table of parameters specific to SPI flash memory devices.

Parameter	Type	Default	Description
`ioModeAddress`	int	1	The SPI I/O mode is used to transmit the address field of the SPI transaction. Possible values are 0, 2 or 4.
`ioModeDataIn`	int	1	The SPI I/O mode is used to receive the data field of the SPI transaction and the possible values are 0, 2 or 4.
`ioModeDataOut`	int	1	The SPI I/O mode used to transmit the data field of the SPI transaction and possible values are 0, 2 or 4.