src/doc/grammar.txt

   1 ====== VUTg Grammar ======
   2
   3 The VUTg is xml, it has tags and values. This section will describe the how to use well this tool. There are severals way to describe the virtual environment that you want to submit your module. Using the right tag with the correct value you can build complexes testbenches which will help you to descrease time in your design and it become fast tests building.
   4
   5
   6 ==== Basics tags ====
   7 All VUTg file must starts with the xml basic definition:
   8
   9         <?xml version="1.0" encoding="UTF-8"?>
  10
  11 The relevants definitions must be included in the vut tag, the **module name** must be write accoding the regexp //r'^[a-zA-z][a-zA-Z0-9_]*$'//, it just can starts with letters and only  accepts the "_" special character. Examples: "module_name","Module_Name","moduleName","M_ODULEN_AME", and so on.
  12
  13         <vut module_name="module_name">
  14                 [//...Module definition...//]
  15         </vut>
  16
  17
  18
  19
  20 ==== Waveform tag ====
  21 This tag is the module's behavior description. The tag is called waveform and must follow be as below:
  22
  23         <waveform>
  24                 =================================
  25                 [...input signal 1...]
  26                 ---------------------------------
  27                 [...input signal 2...]
  28                 ---------------------------------
  29                 [...]
  30                 ---------------------------------
  31                 [...input signal k...]
  32                 =================================
  33                 [...output signal 1...]
  34                 ---------------------------------
  35                 [...output signal 2...]
  36                 ---------------------------------
  37                 [...]
  38                 ---------------------------------
  39                 [...output signal k...]
  40                 =================================
  41         </waveform>
  42
  43
  44
  45
  46
  47 === Input signal ===
  48 There are several input signal formats, it is showed below. It will appear random values called 'Rn', that values will be changed by the compiler for random values constrainted by the user. It will be explained in the future.
  49
  50 * Simple and direct behavior description:
  51
  52         [sig_name]  [bitslice]  i@|val1|val2|val3|...|valk|
  53
  54         Examples:
  55         a i@|1|0|1|1|0|0|1|1|1|0|1|1|0|0|1|
  56         data [31:0]  i@|ffa5e21d|00011ae2|ffffffff|bb03faa2|
  57
  58
  59 * Manually defined random values:
  60
  61         [sig_name]  [bitslice]  i@|val1|...|valk|R1|R2|R3|R2|R3|R3|R4|R4|...|Rk|
  62
  63         Examples:
  64         a  i@|0|0|1|1|1|0|1|0|R1|R2|R3|R2|R2|R3|R1|
  65         data  [31:0]  i@||ffa5e21d|00011ae2|ffffffff|R1|R2|R3|R2|R3|
  66
  67
  68 * Random alocation to the random values, n it is how many times the random values will be applayed://
  69
  70         [sig_name]  [bitslice]  i@|val1|...|valk|random_alloc([R1,R2,...,Rk],n)|
  71
  72         Examples:
  73         a  i@|0|0|1|1|1|0|1|0|random_alloc([R1,R2,R3],100)|
  74         data  [31:0]  i@||ffa5e21d|00011ae2|ffffffff|random_alloc([R1,R2,R3,R5,R6,R7,R8,R9,R10],10000)|
  75
  76
  77 * Using memory to at the val's places
  78
  79         [sig_name]  [bitslice]  i@|include_memory("memory_file.mem")|
  80
  81         Examples:
  82         a  i@|include_memory("in_a.mem")|
  83         data  [31:0]  i@|include_memory("in_data.mem")|
  84
  85
  86
  87
  88 === Output signal ===
  89 There are two output signal formats, it is showed below. It will appear things like that "ref_function([...])" in the output signals, it will be explained in the future.
  90
  91 * Simple and direct behavior description:
  92
  93         [sig_name]  [bitslice]  o@|val1|val2|val3|...|valk|
  94
  95         Examples:
  96         overflow o@|1|0|1|1|0|0|1|1|1|0|1|1|0|0|1|
  97         result [31:0]  o@|ffa5e21d|00011ae2|ffffffff|bb03faa2|
  98
  99
 100 * Using high level language to substitute the reference model:
 101
 102         [sig_name]  [bitslice]  i@|val1|val2|val3|...|valk|ref_function([input_signal1],[input_signal2],[...],  [input_signalk])|
 103
 104         Examples:
 105         data_out i@|1|0|1|1|0|0|1|1|1|0|1|ref_function(data_in,enable)|
 106         data [31:0]  i@|ffa5e21d|00011ae2|ffffffff|bb03faa2|ref_function(data_0,data_1,data_2,data_3)|
 107
 108
 109
 110
 111 ==== Gen_with tag ====
 112 This tag defines the "strange" things that appeared during the text
 113
 114         <gen_with>
 115                 [...Randrange values...]
 116                 [...Python code tag(Reference model functions)...]
 117         </gen_with>
 118
 119
 120
 121
 122 === Randrange values ===
 123 It appeared symbols called Rn where these "represent" random values. The random values are responsible for generating the values used in waverform tag. All the times the values generated will be between the initial and de final values. Each time that the Rn is used the result is generated. The syntax to use it showed below:
 124
 125         [rand_name1] = (init_val,end_final)
 126
 127         Examples:
 128         R1 = (0,f)
 129         R2 = (ff,fffff)
 130         R3 = (aab,f001)
 131         R4 = (9,d)
 132
 133
 134
 135
 136 === Python code tag ===
 137 This tag represents the reference model that will implement functions for emulating the module builded.  You have to implement a Python function which executes the specification. For example a inc module that icrements 1 to the input value (input sinal name inp_val), the reference function must be "lambda inp_val: inp_val + 1"
 138
 139         <python_code ref_function="output_signal_name">
 140                 [...content...]
 141         </python_code>
 142
 143 •Python code
 144
 145         [...function...]
 146
 147         Examples:
 148         "lambda x,y: x + y"
 149         "def result(a,b): return a+b"
 150
 151 * Python source file
 152 It will necessary to implement a method called reference_model into the python file. This method should receive the parameters with exact input signal names. For example, if we want to develop the reference model to the factorial function we have  to define a function "called reference_function(x)", this module must has the x as input signal.
 153
 154         include_python_file("filename1.py")
 155
 156         Examples:
 157         include_python_file("finonacci.py")
 158         include_python_file("fat.py")
 159         include_python_file("mod.py")
 160
 161
 162
 163
 164 ===== Examples =====
 165
 166 Eight bits register
 167