About Source

Directory source contains four kinds of source files.

• top:

  responsible for configuration management and multiple-frame processing.

• kernel:

  responsible for single-frame/multiple-unit processing.

• unit:

  responsible for single-unit processing.

• common:

  responsible for underlying processes.

  (“Frame” here refers to multiple units. “Unit” here refers to the basic block processed by each module.)

Common

Directory common contains collection COMMON,

which is made up of definitions, types, enumerators, structs, tables, and functions

used for information acquiring, data processing, cost calculating, and other underlying processes

Unit

Directory unit contains class UNIT and its inheritors.

As a C model, it should emulate the behaviors of RTL,

while a key feature of RTL is that they usually have several modules and those modules work in a pipeline.

So I create a basic class called UNIT and it acts like RTL modules in the following way.

• In phase new

  all UNITs are newed with their constructor function, which would allocate spaces and assign initial value.
• In phase connect

  all UNITs are connected with function connect, which would note down the address of its previous UNITs according to the pipeline structure
• In phase run

  each UNIT would call function load to load data from its previous UNITs or from files.

  each UNIT would call function proc to process those data.

  each UNIT would call function dump to dump data to files.
• In phase delete

  all UNITs are deleted with their deconstructor function, which would release spaces.

Sure, apart from the above common behaviors,

those UNITs should have some different behaviors to act like different modules in RTL.

Fortunately, this can be realized easily by class inheriting.

Kernel

Directory kernel contains 3 classes.

• class KNL is responsible for single-frame/multiple unit processing.

• class FTH is responsible for single-frame/multiple unit data fetching.

• class DMP is responsible for single-frame/multiple unit data dumping.

Top

Directory top contains file msc.cpp and struct CFG.

file msc.cpp

It is responsible for multiple-frame processing.

struct CFG

It is responsible for configuration management.

During the development of C models, configurations may update frequently.

To reduce the efforts spent on it, I created a script called cfg.pl to maintain them.

where

name	description
msc_cfg.cpp	source file containting function cfgIni, cfgIniFromFile and cfgIniFromCli the former one calls the latter two and all the functions in file cfg_proc.cpp to initialize struct CFG according the contents in configuration files and the parameters in command line interface
msc_cfg.csv	information file containing the domain, name, (opening) level, size, short name, type, minimum value, maximum value, precision, default value and description of each configuration
msc_cfg.pl	script to generate file msc_cfg.hpp, msc_cfg_type.hpp, msc_cfg_proc.cpp, msc_cfg.rst and xkmsc.cfg according to file msc_cfg.csv
msc_cfg.hpp	header file containing the decaration of functions
msc_cfg_type.hpp	header file containing the decaration of struct CFG
msc_cfg_proc.cpp	source file containing the definition of function cfgRst, used to reset struct CFG to the default value function cfgHlp, used to print help information function cfgMap, used to map key-value pair into struct CFG function cfgChk, used to check sanity of struct CFG’s value function cfgLog, used to print struct CFG’s value
msc_cfg.rst	table file in restructedText format
xkmsc.cfg	configuration file to be read by the executable file msc

As shown in the above figure and table, only one file needs to be manually maintained frequently,

which largely reduces the burden to manage configurations

Other Information

Other Information is given below.

Hierarchy

Naming Rule

• macro-definitions

  [<class>_]<type>_<object>[_<modifier1>][_<modifier2>]...[_<modifierN>]
  

  where,

  item	description
  class	short name of class
  type	allowed strings include “KNOB”, “FLAG”, “NUMB”(number), “SIZE”, “ENUM”(enumerator), “DATA”, “FUNC”(function)
  object	allowed strings include “Frame”, “Unit”
  modifier	allowed strings include “MAX”(maximum), “MIN”(minimum), “EXT”(extended), “X”, “Y”, “WD”

• variables

  [<classification>_]<type>_<object>[_<domain>][_<modifier1>][_<modifier2>]...[_<modifierN>]
  

  where,

  item	description
  classification	allowed strings include “m_”(member), “s_”(static table)
  type	allowed strings include “flg”(flag), “num”(number), “idx”(index), “siz”(size), “enm”(enumerator), “dat”(data)
  object	allowed strings include “Ori”(original data), “Coe”(coefficient data)
  domain	allowed strings include “Frame”, “Unit”
  modifier	allowed strings include “Ext”(extended), “Ful”(full), “All”, “Cur”(current), “Bst”(best), “Bfr”(before), “Aft”(after)

• functions

  [<operation>_]<type>_<object>[_<domain>][_<modifier1>][_<modifier2>]...[_<modifierN>]
  

  where,

  item	description
  operation	allowed strings include “cpy”(copy), “get”, “upd”(update)
  type	allowed strings include “flg”(flag), “num”(number), “idx”(index), “siz”(size), “enm”(enumerator), “dat”(data)
  object	allowed strings include “Ori”(original data), “Coe”(coefficient data)
  domain	allowed strings include “Frame”, “Unit”
  modifier	allowed strings include “Ext”(extended), “Ful”(full), “All”, “Cur”(current), “Bst”(best), “Bfr”(before), “Aft”(after)

Configuration

domain	name	size	short key	type	minimum value	maximum value	precision	description
virtual	strFileCfg	/	c	/	/	/	/	location of the configuration file
virtual	help	/	/	/	/	/	/	to print help information
virtual	show	/	/	/	/	/	/	to show configuration value
virtual	dryRun	/	/	/	/	/	/	to check input without running
changeable	idxFrame	1	/	int	/	/	/	index of the current frame
changeable	idxUnitX	1	/	int	/	/	/	index of the current unit in 1st dimension
changeable	idxUnitY	1	/	int	/	/	/	index of the current unit in 2nd dimension
top	strFileIn	1	i	string	/	/	/	full location of the input file
top	strFileOut	1	o	string	/	/	/	full location of the output file
top	strPrefixDump	1	/	string	/	/	/	dump prefix for debug data
top	strPrefixLoad	1	/	string	/	/	/	load prefix for debug data
top	numFrame	1	/	int	/	/	/	number of the frames to be processed
top	sizFrameX	1	/	int	1	4096	/	size of frames in 1st dimension
top	sizFrameY	1	/	int	1	4096	/	size of frames in 2nd dimension
top	sizFrameZ	1	/	int	1	3	/	size of frames in 3rd dimension
top	enmFormatIn	1	/	int	0	1	/	enumerator for input format (<value> 0: yuv420p 1: nv12)
top	enmProc	1	/	int	0	1	/	enumerator for processing behavior (<value> 0: software 1: hardware)
top	enmInfo	1	/	int	0	4	/	enumerator for information level (<value> 0: none 1: system 2: top 3: module 4: common)
top	enmLoad	1	/	int	0	2	/	enumerator for load source (<value> 0: pipeline 1: file 2: random)
top	enmDump	1	/	int	0	2	/	enumerator for dump level (<value> 0: none 1: inout 2: intermediate)
top	datSeed	1	r	int	/	/	/	value of random seed
top	sizUnitX	1	/	int	1	64	/	size of units’ 1st dimension
top	sizUnitY	1	/	int	1	64	/	size of units’ 2nd dimension
scaler	sclFlgProc	1	/	bool	/	/	/	enable flag for processing
scaler	sclNumTap	1	/	int	2	4	/	number of filter tap (<value> 0: 2 1: 4)
scaler	sclSizFrameX	1	/	int	1	8192	/	size of frames in 1st dimension
scaler	sclSizFrameY	1	/	int	1	8192	/	size of frames in 2nd dimension
scaler	sclEnmMode	1	/	int	0	1	/	enumerator for mode (<value> 0: bilinear 1: bicubic)
scaler	sclEnmLoad	1	/	int	0	2	/	enumerator for load source (<value> 0: pipeline 1: file 2: random)
scaler	sclEnmDump	1	/	int	0	2	/	enumerator for dump level (<value> 0: none 1: inout 2: intermediate)
scaler	sclDatThreshold2	1	/	double	0	1	8	threshold for 2-tap filter
scaler	sclDatThreshold4	1	/	int	0	255	/	threshold for 4-tap filter
filter	fltFlgProc	1	/	bool	/	/	/	enable flag for processing
filter	fltEnmLoad	1	/	int	0	2	/	enumerator for load source (<value> 0: pipeline 1: file 2: random)
filter	fltEnmDump	1	/	int	0	2	/	enumerator for dump level (<value> 0: none 1: inout 2: intermediate)
filter	fltDatCoe	3x3	/	double	-16	15.9375	4	coefficient data (<index> Y(0/1/2)~X(0/1/2): value of the coefficient positioned at Y(-1/0/1)~X(-1/0/1))
on-screen-display	osdFlgProc	1	/	bool	/	/	/	enable flag for processing
on-screen-display	osdStrFile0	1	i	string	/	/	/	location of the 0th OSD file
on-screen-display	osdStrFile1	1	i	string	/	/	/	location of the 1st OSD file
on-screen-display	osdStrFile2	1	i	string	/	/	/	location of the 2nd OSD file
on-screen-display	osdStrFile3	1	i	string	/	/	/	location of the 3rd OSD file
on-screen-display	osdStrFile4	1	i	string	/	/	/	location of the 4th OSD file
on-screen-display	osdStrFile5	1	i	string	/	/	/	location of the 5th OSD file
on-screen-display	osdStrFile6	1	i	string	/	/	/	location of the 6th OSD file
on-screen-display	osdStrFile7	1	i	string	/	/	/	location of the 7th OSD file
on-screen-display	osdFlg	8	/	bool	/	/	/	enable flags for OSD (<index> N: the Nth OSD)
on-screen-display	osdSizFrameX	8	/	int	1	4096	/	size of OSD frames in 1st dimension (<index> N: the Nth OSD)
on-screen-display	osdSizFrameY	8	/	int	1	4096	/	size of OSD frames in 2nd dimension (<index> N: the Nth OSD)
on-screen-display	osdPosFrameX	8	/	int	0	4095	/	position of OSD frames in 1st dimension (<index> N: the Nth OSD)
on-screen-display	osdPosFrameY	8	/	int	0	4095	/	position of OSD frames in 2nd dimension (<index> N: the Nth OSD)
on-screen-display	osdEnmLoad	1	/	int	0	2	/	enumerator for load source (<value> 0: pipeline 1: file 2: random)
on-screen-display	osdEnmMode	8	/	int	0	4	/	enumerator for work mode (<index> N: the Nth OSD) (<value> 0: YUV420; 1: AYUV1555; 2: index 2; 3: index 4; 4: ARGB1555)
on-screen-display	osdEnmDump	1	/	int	0	2	/	enumerator for dump level (<value> 0: none 1: inout 2: intermediate)
on-screen-display	osdDatScl	8x2	/	int	1	4	/	scaler data (<index> N-A(0/1): axis A(X/Y) of the Nth OSD)
on-screen-display	osdDatLut0	4x4	/	int	/	/	/	data of 0th OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
on-screen-display	osdDatLut1	4x4	/	int	/	/	/	data of the 1st OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
on-screen-display	osdDatLut2	4x4	/	int	/	/	/	data of the 2nd OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
on-screen-display	osdDatLut3	4x4	/	int	/	/	/	data of the 3rd OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
on-screen-display	osdDatLut4	4x4	/	int	/	/	/	data of the 4th OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
on-screen-display	osdDatLut5	4x4	/	int	/	/	/	data of the 5th OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
on-screen-display	osdDatLut6	4x4	/	int	/	/	/	data of the 6th OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
on-screen-display	osdDatLut7	4x4	/	int	/	/	/	data of the 7th OSD’s LUT (<index> N~C(0/1/2/3): value of channal C(alpha/Y/U/V) of the Nth data)
example	exampleDatInt	1	/	int	0	1	/	an example for int (scalar)
example	exampleDatDouble	1	/	double	0	0.875	8	an example for double (scalar)
example	exampleDatVector	2	/	int	0	1	/	an example for (int) vector
example	exampleDatArray	2x3	/	int	0	1	/	an example for (int) array
derived	numUnitX	1	/	int	/	/	/	number of units in 1st dimension
derived	numUnitY	1	/	int	/	/	/	number of units in 2nd dimension
derived	datScalerX	1	/	double	/	/	16	scaler data in 1st dimension
derived	datScalerY	1	/	double	/	/	16	scaler data in 2nd dimension
derived	sclDatThreshold2Inv	1	/	double	/	/	8	threshold for 2-tap filter divided by 1

Macro-Definition

Domain	Name	Description
TOP	KNOB_… FLAG_… NUMB_… SIZE_… ENUM_… DATA_… FUNC_… …	knob of … flag for … number of … size of … enumerator for … data of … function of … …
KERNEL	KNOB_… FLAG_… NUMB_… …	knob of … flag for … number of … …
UNIT	…	…
COMMON	…	…

Please refer to source/common/common.hpp for more information.