Memdata - Data Conversion¶
Memdata is a simple tool used to convert memory preloading data between various formats for simulation purpose.
Currently Memdata has following features:
Support Multi-formats inter-conversion
Support write-out format extension based on template
Support byte resolution arrangement and bit resolution output
Support address range and address skipping
Support big / little endian
Interactive mode and useful command
Batch mode
GUI mode - T.B.D
To get the command syntax, run below command:
$> qk memdata -h
usage: qk memdata [-h] [-f CMDFILE] [-g] [-i] [-k KIND] [-t TYPE] [-o OUT]
[-code] [-endian] [-range RANGE] [-atom ATOM]
[-atomgap ATOMGAP] [-atompos ATOMPOS] [-maxsize MAXSIZE]
[-bits BITS] [-bin]
[infile]
positional arguments:
infile Input design file
optional arguments:
-h, --help show this help message and exit
-f CMDFILE, --cmdfile CMDFILE
Command file
-g GUI mode
-i Interactive mode
-k KIND Input file type
-t TYPE Output file type/template
-o OUT Output filename
-code Code data
-endian Data endian
-range RANGE Address range in format: "start:end"
-atom ATOM Data output atom size in byte
-atomgap ATOMGAP Gap between sequential atom, count of atom
-atompos ATOMPOS Position of skipped atom
-maxsize MAXSIZE Max size in byte of dump file
-bits BITS Bit range of Atom, format as <high:low>
-bin Input format as binary
Concept¶
Memory model normally needs one or more TXT file(s) for memory content initialization when simulation begins. And the content of TXT file has to comply some format rule, which is defined by the memory model.
The key points for format conversion is the memory data width and depth. Memdata uses the name ATOM to represent the data width in bytes, i.e. 8-bit width means 1 of ATOM, and 16-bit width means 2 of ATOM, 17-bit means 3 of ATOM.
In some model, BANK concept is used, and data is continuous over banks, and within one bank the data is not continuous. The switch -atomgap is used to represent the number of banks: \(atomgap+1\), i.e. -atomgap 7 if has 8 banks. And switch -atompos to specify which bank data is to be generated, starting from 0.
If there is data-size limit of a single data file, switch -maxsize can be used for this purpose. Memory content will be split into serveral files, in this case, the output filename should contain %d for indexing. i.e. -o out%d.txt -maxsize 0x400.
For those memory which is made up of several physical memories, especially data width is joined by more than 2 memories, data bits are split over memories, then for a single physical memory, the data is slice of a data ATOM. Use switch -bits high:low to extract the correct bit slice.
Supported Formats¶
Current Memdata support 4 Read/Write formats and 4 Write templates.
Intel HEX format - Read/Write
Motorola S format - Read/Write
ARM format - Read/Write
CEVA4500 format - Read/Write
mem-vhdl - Write - VHDL memory model format template
mem-verilog - Write - Verilog memory model format template
mem-vcs - Write - VCS memory loading format template
mem-generic - Write - Generic memory model format template
For Read/Write formats, file extension can be used to indicate the format:
Intel HEX format - .hex
Motorola S format - .s2
ARM format - .arm
CEVA4500 format - .vhx
When a provided input file extension can’t indicate the format, user has to explicitly specify the format by switch -k. Or a output file extension can’t indicate the format, the switch -t can be used. Switch -t is also used to specify the output template.
Below command convert HEX file xxx.phex into ARM format file a.vhx or b.txt:
$> qk memdata -k hex -o a.vhx xxxx.phex
$> qk memdata -k hex -t arm -o b.txt xxxx.phex
For ARM format, if input format is in binary instead of hex, the switch -bin can be used for specify this situation.
Template¶
Memdata has some builtin templates, located at: templates/mako/memdata/.
mem-vhdl.mako
mem-verilog.mako
mem-vcs.mako
mem-generic.mako
To make this tool be extensible, when a new data file format is not supported by the builtin formats and templates, user can create a new template to describle the data format, and put the template file at builtin location or current directory, then run command like::
$> qk memdata -t <template> <input-data-file>
To write a template, user has to learn the Mako syntax first, and then also need to know the varialbe context, which Memdata passes to the template.
Mako Variable Context¶
Variable context is the namespace through which Memdata passes processed data to Mako template. Template author can display some of the data in some format.:
start : Start address of data, default as 0.
end : End address of dada, default to end of whole data.
endian : Reverse byte order if set to True.
atoms : List of data-unit, this is the main data user need to expand.
atomsize : Byte-count of data-unit, represents the physical memory data width in byte.
atomgap : Data-unit skipping steps, 0 means no skipping.
bits : Bit slice of the data-unit, in format: <high:low>.
mem : Dict object of tool core data, key:value pair is address:data pair.
Interactive Mode¶
Interactive Mode is entered with switch -i. And user can type individual command one after one to see internal data and states.:
$> qk memdata -i
This tool is used for memory data processing
memdata:>
Below commands are supported:
load¶
Command load is used to load in a data file, which in supported format.:
memdata:> load -h
usage: load [-h] [-t TYPE] filename
positional arguments:
filename Design file to load
optional arguments:
-h, --help show this help message and exit
-t TYPE Design file type
save¶
Command save is used to write out a data file, in supported format.:
memdata:> save -h
usage: save [-h] [-t TYPE] filename
positional arguments:
filename Design file to load
optional arguments:
-h, --help show this help message and exit
-t TYPE Design file type
fill¶
Command fill is used to fill a fixed value in continuous address range.:
memdata:> fill -h
usage: fill [-h] [-a ADDR] [data]
positional arguments:
data Data to fill
optional arguments:
-h, --help show this help message and exit
-a ADDR Address(range) to fill
erase¶
Command erase is used to remove data in continuous address range.:
usage: erase [-h] [-a ADDR]
optional arguments:
-h, --help show this help message and exit
-a ADDR Address
Batch Mode¶
Batch mode is entered when you provide a command file to the tool, like below:
$> qk memdata -f a.cmd
All commands supported in Interactive Mode are also supported in Batch mode.
Blank lines and comment lines are ignored by tool. Comment starts with ‘#’, till end of line.
GUI Mode¶
T.B.D