====== The Component ======

In Arx, the component is the basic building block of hardware,
comparable to a 
//module// in Verilog or the //entity-architecture// combination in
VHDL.

===== Example 1: Register =====

The code below shows one of the simplest components that one could
describe in Arx (say, the //hello world// of Arx). It represents a
single register. So, at each rising edge of the clock the component copies the data at its input to its output.


<code arx copy.arx>
component top 
    T_IO        : generic type = bitvector(8)
    data_in     : in T_IO
    data_out    : out T_IO

register
    storage     : T_IO = 0

begin
    storage = data_in
    data_out = storage
end
</code>

The code contains the following information:
  * The component is called ''top''.
  * All signals in this component have data type ''T_IO''. It is a //generic type// which means that the type can be given a value at [[instantiation]] time.
  * The default value of ''T_IO'' is ''bitvector(8)'' which represents a bundle of 8 binary signals numbered 7 down to 0. The page dedicated to [[datatypes|Arx data types]] gives more information on available data types.
  * ''data_in'' is an input signal of the component as indicated by the keyword ''in''.
  * ''data_out'' is an output signal of the component as indicated by the keyword ''out''.
  * Even when the component is synchronous, the clock and reset signals are not explicit. They will be automatically added to the generated VHDL code. The page on [[cpp_sim|C-based simulation]] explains how to deal with clock and reset when using the generated C-code for simulation.
  * The component contains a register called ''storage'' with the same width as ''data_in'' and ''data_out''. 
  * ''data_in'' connects to the input of this register, and ''data_out'' to the output.  
  * The equal sign ''='' represents a signal assignment, a connection from the right-hand side to the left-hand side.
  * The equal sign ''='' is also used to specify the reset value of registers. The language requires that all registers have a reset value.
  * Assignments to registers follow the semantics of synchronous systems (see the page on [[rtl|RTL]]). A register in the right-hand side of an assignment produces the value clocked into the register after the last rising edge of the clock. A register in the left-hand side of an assignment refers to the next value that will be clocked in.


===== Example 2: A Clearable Accumulator =====

The example below is a somewhat more sophisticated design. Next to a
register, it has some combinational logic.  It
represents a //clearable accumulator// which adds a sequence of
numbers and outputs the result.

<code arx reg-cascade.arx>
component top
  wl: generic integer = 12
  T_in : generic type = signed(wl  , 1)
  T_out: generic type = signed(wl-2, 1, sat, round)
  T_sum: generic type = signed(wl+5, 6)
  clear: in bit
  data_in : in  T_in
  data_out: out T_out
variable
  sum: T_sum
register
  r: T_sum = 0
begin
  if clear == 1
     sum = data_in
  else
     sum = r + data_in
  end
  r = sum
  data_out = r
end
</code>

Remarks:
  * The component has two internal signals: register ''r'' and wire ''sum''. Wires (signals that do not keep their value across clock cycles) are declared after keyword ''variable''.
  * The data type used for the data path is fixed-point.
  * The intended behavior of this circuit is that inputs are accumulated in a register with more bits that the input, but that the output has fewer bits. The latter requires handling of overflow and quantization (in this case saturation and rounding) which is automatically performed in the generated code (both C and VHDL).  See the section on [[datatypes|Arx data types]] for a detailed explanation.
  * Another intended behavior is that the accumulator is cleared by directly copying the input to it when the signal ''clear'' is high. This is expressed by the if statement which is presented in more detail in the section on [[statements|Arx statements]].
  * The picture below depicts the circuit implied by this description (without the signal data types).

{{ :arx:acc-data-path.png?300 }}

===== General Structure =====
The pseudo-code below lists all possible constituents of a component.

  component <component name>
    <generic declarations>
    <generic type declarations>
    <i/o declarations>
    <constant declarations>
    <type declarations>
    <register declarations>
    <variable declarations>
    <subcomponent instantiations>
  begin
    <statements>
  end

===== Known Issues =====

The top-level component needs to be called ''top'' in the current version
of Arx.