------------------------------------
XML description of a block model :
------------------------------------

<parameter> attributes :
  - name : required
  - type : required
  - value : required if context = constant/generic, optionnal if context = wb, optional but not used if context = user/port
  - context : required
  - 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
    that is read by the core, i.e. an input port of the core, or written by the core.

<inputs>, <outputs> attributes :
  - name : required
  - width : required
  - purpose : optional. Possible values : clock, reset, wb, data, ... Default value is data
  - multiplicity : optional. Possible values : *, a number. Default value is 1.

<bidirs> attributes :
  - name : required
  - width : required
  - purpose : optional but forced to data
  - multiplicity : optional. Possible values : *, a number. Default value is 1.
  If an interface has a multiplicity > 1, the user will be able to create several
  instances of that interface. Their default name will be the reference name
  followed by _X, where X = 1, ..., N, and N the number of instances.

  
--------------------------------------------
XML description of an implementation model :
--------------------------------------------

<block_impl> attributes:
  - 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.
  - 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.

<comments> block:
  - all elements and their attributes are amndatory but they can be void.

<libraries> block:
  - used to generate the library and use instructions.
  - in case of using a standard package (from work or std), only use clauses will be generated.

<architecture> block:
  - constains only the architecture part of the implementation
  - 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.

syntax:

  - @{input/output/bidir} is replaced by the "real" name in the pgrah
    of blocks. It is because the reference name given in the reference
    block may be changed by the user for a specific instance of that
    block in the graph. Using @{name} will lead to do produce a VHDL
    code with the name given by the user and not the reference name.

  - @{param} is replaced by the name of the parameter as given in the reference
    blokc, which cannot be changed by the user.

  - @val{param} is replaced by the value of the parameter. This value may be
    constant, given by user, or sometimes computed according to number of
    instances of an interface with multiplicitiy>1.

  - @eval(expression) is replaced by the result of the evaluation of th arithmetic expression.
     This expression can use +,-,*,/,(,), numbers and values of params, i.e. @val{param} expressions.
     BEWARE : using a generic param value in an @eval{} is inadvisable, since it breaks the principles of
     the generic use.
     
  - @foreach{interface}
      // instructions
    @endforeach

    only applicable to interfaces with multiplicity>1. Used to produce
    a sequence of instruction X times, where X is the number of
    interface instances created by the user. For each of those interfaces,
    instructions will be generated. If ${interface} is used
    within the instructions, it will be replaced by the actual evaluated interface.

    Example : let val_o an output interface with multiplicity="*"
    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.
    Then, if an implementation contains :
    @foreach{val_o}
    signal @{val_o}_enb : std_logic;
    @endforeach

    Then the generated VHDL is :
    signal val_o_1_enb : std_logic;
    signal val_o_2_enb : std_logic;
    signal val_o_last_enb : std_logic;

  - @caseeach{interface,signal,cases}
      // instructions
    @endcaseeach

    similar to foreach but to produce a case statement. signal is the
    signal used to test against the cases. Obviously, there should be
    as much cases as the number of interface instances. If not, the
    generation will not be complete.
    cases may be a predefined variables (see below) or a list of values.

    Example : with the same assumptions as in foreach example,
    
    @caseeach(val_o,sel_s,@#:1)
      @{val_o}_enb <= '1';
    @endcaseeach

    will produce
    case sel_s is
       when 1 => val_o_1_enb <= '1';
       when 2 => val_o_2_enb <= '1';
       when 3 => val_o_last_enb <= '1';
    end case;

  - @#[-]:number : only usefull within foreach, caseeach, ... Produces an output
    that starts at number and increments or decrements (with #-) at each case.

    Example : @#-:3 will produce 3, 2, 1, 0, -1, ...