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