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