]> AND Private Git Repository - blast.git/blob - lib/README.txt
Logo AND Algorithmique Numérique Distribuée

Private GIT Repository
added an example of source block
[blast.git] / lib / README.txt
1 ------------------------------------
2 XML description of a block model :
3 ------------------------------------
4
5 <parameter> attributes :
6   - name : required
7   - type : required
8   - value : required if context = constant/generic, optionnal if context = wb, optional but not used if context = user/port
9   - context : required
10   - wishbone : required if context = wb, not used for others. Possibles values : r or w,keep_value,type_init. Specify if the parameter will be a register
11     that is read by the core, i.e. an input port of the core, or written by the core.
12
13 <inputs>, <outputs> attributes :
14   - name : required
15   - width : required
16   - purpose : optional. Possible values : clock, reset, wb, data, ... Default value is data
17   - multiplicity : optional. Possible values : *, a number. Default value is 1.
18
19 <bidirs> attributes :
20   - name : required
21   - width : required
22   - purpose : optional but forced to data
23   - multiplicity : optional. Possible values : *, a number. Default value is 1.
24   If an interface has a multiplicity > 1, the user will be able to create several
25   instances of that interface. Their default name will be the reference name
26   followed by _X, where X = 1, ..., N, and N the number of instances.
27
28   
29 --------------------------------------------
30 XML description of an implementation model :
31 --------------------------------------------
32
33 <block_impl> attributes:
34   - ref_name: the name of an XML file that contains the block model associated to this implementation. Normally, it should be unique over all available blocks.
35   - ref_id : the md5 hashsum of the xml file given in ref_name. It is used to quickly retrieve the block model in the applciation.
36
37 <comments> block:
38   - all elements and their attributes are amndatory but they can be void.
39
40 <libraries> block:
41   - used to generate the library and use instructions.
42   - in case of using a standard package (from work or std), only use clauses will be generated.
43
44 <architecture> block:
45   - constains only the architecture part of the implementation
46   - the name of the architecture will be determined automatically from the number of existing implementations for the block model. The name will be the name of the block followed by _X, where X is the rank of the implementation found when directories are parsed to found implementations.
47
48 syntax:
49
50   - @{input/output/bidir} is replaced by the "real" name in the pgrah
51     of blocks. It is because the reference name given in the reference
52     block may be changed by the user for a specific instance of that
53     block in the graph. Using @{name} will lead to do produce a VHDL
54     code with the name given by the user and not the reference name.
55
56   - @{param} is replaced by the name of the parameter as given in the reference
57     blokc, which cannot be changed by the user.
58
59   - @val{param} is replaced by the value of the parameter. This value may be
60     constant, given by user, or sometimes computed according to number of
61     instances of an interface with multiplicitiy>1.
62
63   - @eval(expression) is replaced by the result of the evaluation of th arithmetic expression.
64      This expression can use +,-,*,/,(,), numbers and values of params, i.e. @val{param} expressions.
65      BEWARE : using a generic param value in an @eval{} is inadvisable, since it breaks the principles of
66      the generic use.
67      
68   - @foreach{interface}
69       // instructions
70     @endforeach
71
72     only applicable to interfaces with multiplicity>1. Used to produce
73     a sequence of instruction X times, where X is the number of
74     interface instances created by the user. For each of those interfaces,
75     instructions will be generated. If ${interface} is used
76     within the instructions, it will be replaced by the actual evaluated interface.
77
78     Example : let val_o an output interface with multiplicity="*"
79     Supposing the user created 3 instances, leaving the two first with their default name (i.e. val_o_1 val_o_2) and the last one with name val_o_last.
80     Then, if an implementation contains :
81     @foreach{val_o}
82     signal @{val_o}_enb : std_logic;
83     @endforeach
84
85     Then the generated VHDL is :
86     signal val_o_1_enb : std_logic;
87     signal val_o_2_enb : std_logic;
88     signal val_o_last_enb : std_logic;
89
90   - @caseeach{interface,signal,cases}
91       // instructions
92     @endcaseeach
93
94     similar to foreach but to produce a case statement. signal is the
95     signal used to test against the cases. Obviously, there should be
96     as much cases as the number of interface instances. If not, the
97     generation will not be complete.
98     cases may be a predefined variables (see below) or a list of values.
99
100     Example : with the same assumptions as in foreach example,
101     
102     @caseeach(val_o,sel_s,@#:1)
103       @{val_o}_enb <= '1';
104     @endcaseeach
105
106     will produce
107     case sel_s is
108        when 1 => val_o_1_enb <= '1';
109        when 2 => val_o_2_enb <= '1';
110        when 3 => val_o_last_enb <= '1';
111     end case;
112
113   - @#[-]:number : only usefull within foreach, caseeach, ... Produces an output
114     that starts at number and increments or decrements (with #-) at each case.
115
116     Example : @#-:3 will produce 3, 2, 1, 0, -1, ...
117