FlashLink Device DB Structure

Scope and use of the DB

FlashLink uses a database (DB) to store information about all supported devices. This database is essential for exporting the device.db file, which is used by the Workbench software to guide customers in creating their projects. Additionally, the database is used to extract the DevData.xml file for each driver required to program the device correctly.

How to acces the DB

The DB is stored on a cloud server at address fndb.siliflash.ovh and it's managed by a MySQL server. To access it any MySQL client can be used. To connect you need to use the following credentials:

  • Login: fn
  • Password: sm1502sy
  • Database: fn

To enter the data use your preferred MySQL client to connect, than insert the required data as documented below.

How the DB is used

The database is used solely as a cloud repository for storing data about the devices to be programmed. It is never accessed directly by the programmer or the Workbench. Instead, the required data must be extracted and converted into a proprietary format that can be utilized by the Workbench and the drivers on the programmer.

The Workbench uses a file called device.db, stored on the PC, which contains descriptions of all supported devices. Each driver, on the other hand, requires a dedicated file called DevData.xml that includes data only for the devices it directly supports. This file is needed during the compilation step, as it will be included in the driver's compiled library.

How to export the data

To export the data from this DB there is a specific program callad exportDB. This program is already configured with the configuration and credentials required to connect to the DB and convert the data. The usage is as follows:

To export the device.db file for the Workbench:

exportDB ALL device.db

To export the DevData.xml file required by the driver:

exportDB <driverName> DevData.xml

where <driverName> is the name of the driver as saved on the DB.

The contents of these files are encrypted for security. During development, it is possible to export these files in clear XML format for review by the developer by adding XML as the last parameter. For example:

exportDB CORTEX DevData.xml XML

The files exported in this way can be checked by the developer to find problems with the DB data, but cannot be used by the driver.

Fast-track db export

The SQL connection over the internet is very slow. To retrieve the data quickly, the export utility is also installed on the server. To export the data, create a bash script on your Linux machine with the following content:

#!/bin/bash

rm device.db 2>&1 >/dev/null
ssh flashlink@fndb.siliflash.ovh /home/flashlink/export.sh $1
scp flashlink@fndb.siliflash.ovh:/home/flashlink/device.db.gz .
gunzip device.db.gz

Then run this script with one single argument that is the name of the driver. To export the complete DB for the workbench use ALL as driver name.

For example, having the script named as remoteExport.sh you can run it as:

sh remoteExport.sh ALL

The script asks for a password two times (the password to be used is fl1502csm), then the exported data will be saved inside a file called device.db on the current directory.

List of tables

Table Description
Drivers Lists all the drivers.
DriversOptions Lists the custom options required by each driver.
Protocols Lists the protocols available for the drivers to use.
Device Lists all the supported devices.
DevData Provides additional parameters for each device required by the driver.
MemRegion Lists the memory regions for each device memory
MemType Lists the types of memory available on devices.
MemRemap Describes memory address remapping for certain devices.
Drivers_Device Associates drivers with devices to add device support.
PinMap Lists the usage of the programmer's DIO lines for specific protocols.
uKernel Lists the available microkernels.
uKernelParam Specifies arguments required by the microkernel (currently unused).
Commands Lists custom commands implemented by the driver.
CommandParam Lists the parameters required for each custom command.
CommandChoice Lists the alternative values available for commands with a fixed list.
Manufacturers Lists all silicon producers.
Family Lists the silicon device families
Subfamily Lists the subfamilies of devices.
Core Lists the core architecture of devices.
Voltages Lists supported voltage ranges for devices.
ProgrammingTimes Lists the programming times for each tested device.

The minimum required table to update

For a new device

To add a new device to an existing driver you need to add data to the following table:

  • Device
  • the basic device information
  • Driver_Device
  • required to define which driver is needed to program this device (without this entry the device will not be exported)

Normally, the memory map of the device differs from the already supported devices, so the following tables must also be updated:

  • MemType
  • The type of memories present in the device
  • MemRegion
  • The description of the memory map of the new device

For a new driver

To add a new driver to the DB the following tables have to be updated:

  • Drivers
  • Protocols

Tables Structure

Table Drivers

Column Type Key Description
idDriver varchar(30) Y Id of the driver (used on the code and on other table)
DriverName varchar(30) N Name of the driver as shown on the Workbench (normally the same as idDriver)
libName varchar(40) N name of the exported .so driver file on linux
Data date N Date of latest driver release (currently not updated)
Note longtext N Notes on the driver (not exported, useful as developer notes)
docFileName varchar(40) N Name of the file with the user documenation (not used, for future development of the workbench)
internalId varchar(20) N Unique hexadecimal number for driver identification

There should be one entry in this table for each driver available for the programmer

Table DriverOptions

Column Type Key Description
idDriver varchar(30) Y Link to Drivers table (external key)
OptionName varchar(30) Y Name of the option (as shown on the workbench)
User int N 1 => The option value will be entered by the user
Optional int N 0 => The option must be set in the project, 1 => The option can be inserted by the user but is optional
OptionType int N Type of the value for this option (see Type of option value table)
MinVal varchar(40) N Minimum admissible value (for validation by the WorkBench)
MaxVal varchar(40) N Maximum admissible value (for validation by the WorkBench)
DefVal varchar(40) N Default value to inserted by the Workbench at new project creation
Label varchar(40) N Label to be shown by the workbench next to the input box
Descr varchar(80) N Description of the option shown by the workbench
editClass varchar(40) N Not Used

Only for drivers that require custom, user-configurable settings to be passed from the script to the driver.

Type of option value

Idx Type
0x00 Char
0x01 String
0x02 UINT 8
0x03 UINT 16
0x04 UINT 32
0x05 UINT64
0x06 BOOL
0x10 Char
0x11 String
0x12 UINT 8
0x13 UINT 16
0x14 UINT 32
0x15 UINT64

Table Protocols

Column Type Key Description
idDriver varchar(30) Y Link to Drivers table (external key)
idProtocol varchar(30) Y Protocol ID
protocolName varchar(30) N Name of the protocol (as shown by the workbench)
idPinMap int N Link to PinMap table (external key)
maxCommFreq int N Max communication frequency supported by the protocol
minCommFreq int N Min communication frequency supported by the protocol
defCommFreq int N Default communication frequency to be set by the workbench

This table links each driver with the protocol it supports. At least one entry is required for a driver to be used.

Table Device

Column Type Key Description
idDevice varchar(30) Y Id of the device (normally the same as the partnumber)
Device varchar(30) N Device name (nart number)
idManufacturer varchar(30) Y Link to Manufacturers table (external key)
idFamily varchar(30) N Link to Family table (external key)
idSubfamily varchar(30) N Link to subfamily table (external key)
IDCODE varchar(20) N IDCODE of the device (used by the driver to check the device)
IDCODE_MSK varchar(20) N Mask to be used with the IDCODE field to verify the device code
IDCODE2 varchar(20) N Second IDCODE of the device (Used only by some drivers)
FlashType varchar(20) N Not used
idVoltages varchar(30) N Link to Voltages table (external key)
idMemoryMap varchar(30) N Link to MemRegion and MemType tables (used to represent the memory map of the device, (external key))
idCore varchar(30) N Link to Core table (external key)
internaID varchar(20) N Unique hexadecimal value for device identification (not used at the moment)
clkMin int N Minimum input clock frequency of the device
clkMax int N Maximum input clock frequency of the device
clkDef int N Default input clock frequency of the device
pllMin int N Min core clock frequency using the PLL for the device
pllMax int N Max core clock frequency using the PLL for the device
pllDef int N Default core clock frequency using the PLL for the device
devData1 int N Generic parameter, the meaning is defined by the driver
devData2 int N Generic parameter, the meaning is defined by the driver
devData3 varchar(20) N Generic parameter, the meaning is defined by the driver
devData4 varchar(20) N Generic parameter, the meaning is defined by the driver
devData5 varchar(20) N Generic parameter, the meaning is defined by the driver
devData6 varchar(20) N Generic parameter, the meaning is defined by the driver
devData7 varchar(20) N Generic parameter, the meaning is defined by the driver
devData8 varchar(20) N Generic parameter, the meaning is defined by the driver
supported int N 1 => supported, 0 => not supported (to be used for inserting device data before completing the driver)
tested int N 1 => The device was tested
docFileName varchar(40) N Name of the file with the user documenation (not used, for future development of the workbench)
hidden int N 1 => Do not show the device on the device list (only for marketing purpose, not used by development tools)

This table contains all the devices supported with the required information. The fields DevData<n> are used to save specific data of each device. The meanings of these fields depend on the driver and must be documented on the file readme.md inside the driver source code directory.

Table DevData

Column Type Key Description
idDriver varchar(30) Y Link to Drivers table (external key)
idDevice varchar(30) Y Id of the device (normally the same as the partnumber)
OptionName varchar(30) Y Name of the option value
Value varchar(40) N Value to be passed to the driver

Specific data about each device, the prefered way to save device specific data is through the DevData<n> fields within the Device table. This table is used when the 10 fields are not sufficient.

Table MemRegion

Column Type Key Description
idMemoryMap varchar(30) Y Id of the memory map, link to Device table (external key)
idMemType varchar(30) Y Link to MemType table (external key)
idMemRegion int Y Id of the Memory Region
idx int N Used for ordering the regions in the view displayed by the Workbench
StartAddr varchar(20) N Start address of the memory region (in hex with the 0x prefix )
EndAddr varchar(20) N End address of the memory region (Last valid address) (in hex with the 0x prefix )
EraseBlockSize varchar(20) N Block size for the erase operation (in hex with the 0x prefix )
ProgramBlockSize varchar(20) N Block size for the program operation (in hex with the 0x prefix )
EraseBlockSizeL2 varchar(20) N Block size for the erase operation (Level2) (in hex with the 0x prefix )
ProgramBlockSizeL2 varchar(20) N Block size for the program operation (Level2) (in hex with the 0x prefix )
EraseBlockSizeL3 varchar(20) N Block size for the erase operation (Level3) (in hex with the 0x prefix )
ProgramBlockSizeL3 varchar(20) N Block size for the program operation (Level3) (in hex with the 0x prefix )
SubSectorSize int N Available for custom use by the driver
regAddr varchar(20) N Address of flash module, driver specific use (in hex with the 0x prefix )
SecurityRelated int N 1 => Section with security or protection info (driver specific use)
blankValue varchar(20) N Value of the memory after erased (in hex with the 0x prefix )
BankIdx int N Available for custom use by the driver
BlockIdx int N Available for custom use by the driver
Dat1 varchar(20) N Generic parameter for custom use by driver (in hex with the 0x prefix )
Dat2 varchar(20) N Generic parameter for custom use by driver (in hex with the 0x prefix )
Dat3 varchar(20) N Generic parameter for custom use by driver (in hex with the 0x prefix )
Dat4 varchar(20) N Generic parameter for custom use by driver (in hex with the 0x prefix )
Dat5 int N Generic parameter for custom use by driver
Dat6 int N Generic parameter for custom use by driver
Dat7 int N Generic parameter for custom use by driver
Dat8 int N Generic parameter for custom use by driver

This table describes the memory map of each device. For each device there are more rows in this table, each row describes one contiguous memory region. Also every memory region is linked to the MemType table with valid information for all the region that are part of the same memory type (like for example FLASH or EEPROM)

Fields Dat<n> are used to save specific information required by the driver. The meanings of these field are driver dependent and must be documented on the file readme.md inside the driver source code directory.

Table MemType

Column Type Key Description
idMemoryMap varchar(30) Y Id of the memory map, link to Device table (external key)
idMemType varchar(30) Y Id of the MemType for this memory type
MemType varchar(40) N Name of this memory type (will be shown in the workbench)
idx int N Used for ordering the regions in the view displayed by the Workbench
Flag char N Single char to identify this memory type on the project (like in DRVPROGRAM F)
Help Text N Text to be shown in the Workbench. NOT USED at the moment
canDelete Int N 1 => This memory can be erased
canBlankcheck Int N 1 => This memory can be blank checked
canProgram Int N 1 => This memory can be programmed
canVerifyReadout Int N 1 => This memory can be verified reading out his content
canVerifyChecksum Int N 1 => This memory can be verified by checking its checksum
canREadDump Int N 1 => This memory can be read back and dumped
wordsize int N Word Size: 1 => Normal byte addressed 2 => Word (16bits) addressed 4 => Word (32bits) addressed
Offset varchar(20) N Available for the driver
NoDefCmd int N 1 => The workbench doesn't insert commands for this memory type on the default project script

Each row contains information of a specific memory type of the Memory Map.

Table MemRemap

Column Type Key Description
idMemoryMap varchar(30) Y Id of the memory map, link to Device table (external key)
idMemRemap varchar(30) Y Id of the memory memapping for the linked memory map
StartAddr varchar(20) N Start address of the region to be remapped (Target address inside the source file) (in hex with the 0x prefix )
Len varchar(20) N Length of the region (in hex with the 0x prefix )
Op int N Operation to be applied on the address (see MemRemap operation table)
Value varchar(20) N Value to be used with the previous operation to calculate the new address (in hex with the 0x prefix )
note text N Notes for developers

This table is rarely required. Some devices have memory that, during programming, uses different addresses than those used in the development environment and in the generated .hex or .mot files. This table contains the information to convert the addresses present in the .hex file to the correct addresses to be used during programming.

MemRemap operation

Op Operation Name Description
1 OR (SrcAddr OR Value) => Target Addr
2 AND (SrcAddr AND Value) => Target Addr
3 ADD (SrcAddr + Value) => Target Addr
4 SUB (SrcAddr - Value) => Target Addr

Table Drivers_Device

Column Type Key Description
idDriver varchar(30) Y Link to the Drivers table (external key)
idDevice varchar(30) Y Link to the Device table (external key)
idProtocol varchar(30) Y Link to the Protocols table (external key)
iduKernel varchar(30) N Link to the uKernel table (external key)
showOnDevList int N 0 => hide from device list (not used at the moment)

This table links each device with the driver that supports it. Only devices present on this table are shown by the Workbench.

Table PinMap

Column Type Key Description
idPinMap int Y Id of this pinMap
idxPinMap int Y Idx used for pinmap with more than 8 pins (otherwise always 0)
PinMap varchar(30) N Name of the pinmap (as shown on the Workbench)
descr varchar(30) N Description of this pinmap
DIO00 varchar(20) N Name of the line connected to the DIO0 output pin
DIO01 varchar(20) N Name of the line connected to the DIO1 output pin
DIO02 varchar(20) N Name of the line connected to the DIO2 output pin
DIO03 varchar(20) N Name of the line connected to the DIO3 output pin
DIO04 varchar(20) N Name of the line connected to the DIO4 output pin
DIO05 varchar(20) N Name of the line connected to the DIO5 output pin
DIO06 varchar(20) N Name of the line connected to the DIO6 output pin
DIO07 varchar(20) N Name of the line connected to the DIO7 output pin
Note text N Notes for the developer

This table contains information to be shown to the user for him to be able to connect the programmer to the target device.

Table uKernel

Column Type Key Description
iduKernel varchar(30) Y Id of this uKernel
uKernelFileName varchar(30) N Name of the file of the uKernel
CodeAddr varchar(20) N Address where the uKernel has to be loades (in hex with the 0x prefix )
DataAddr varchar(20) N Address of the buffer to exchange data with the uKernel (in hex with the 0x prefix )
StackAddr varchar(20) N Address where to set the Stack for the uKernel (in hex with the 0x prefix )
Addr1 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr2 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr3 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr4 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr5 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr6 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr7 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr8 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr9 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )
Addr10 varchar(20) N Generic address for the uKernel to use (in hex with the 0x prefix )

Each driver that uses a uKernel uses this table to find the uKernel code, the information on how to transfer it to the target device and how to use it.

Table Commands

Column Type Key Description
idDriver varchar(30) Y Link to the Drivers table (external key)
idCommand varchar(30) Y Id of this command
idx int N Used to define the order of the command on the script creation
CommandText varchar(30) N Command as inserted into the script
idSezione int N At the moment not used
NumParams int N Total number of the parameters (optional and mandatory) used by this command
OptionalParams int N How many parameters are optional (Optional params must be at the end)
Descr varchar(200) N Description of the command for the user
objClass varchar(20) N Not used
posHint int N Not used at the moment
Default int N 1 => the command is inserted by default on a new script

Table CommandParam

Column Type Key Description
idDriver varchar(30) Y Link to the Drivers table (external key)
idCommand varchar(30) Y Link to the Commands table (external key)
idx int N Index of this parameter
Type int N Value type for this parameter, see description under table DriverOptions
Descr varchar(100) N Description of the parameter usage
Name varchar(30) N Name of the parameter (as shown by the workbench)

Table CommandChoiche

Column Type Key Description
idDriver varchar(30) Y Link to the Driver table (external key)
idCommand varchar(30) Y Link to the CommandParam table (external key)
idxParam int Y Index of the parameter
Order int Y Order of this choice value in the dropdown view of the workbench
Value varchar(40) N Value of this choice to be passed to the command
Descr varchar(100) N Description for the user shown by the Workbench

DB As seen from the driver

All the information entered into the database is made available to the driver code and is accessible through the function parameter ctx, found within the device field. The correct way to access this data is by using the FN_getDevData function. To retrieve information about the device's memory map, use the FN_getMemtable function.

Within that structure, all data from the Device table is directly stored in the corresponding fields. Additionally, the memMap field contains data from the MemType table and the related MemRegion table. The algo field, on the other hand, contains data from the Drivers table.

To see all the available fields, refer to the files ctxManTypes.h and soapStub.h. The connection between the table data and the structure fields is straightforward.