===============
Input component
===============

* **Input component**
* :ref:`Quality assurance component <user_guide_qa>`
* :ref:`Approximation component <user_guide_approx>`
* :ref:`Estimation component <user_guide_estimation>`
* :ref:`Search component <user_guide_search>`
* :ref:`Output <user_guide_output>`


.. Input component
.. ===============

.. _user_guide_input:

Component description
---------------------

The *input* component handles primarily the detection of approximation candidates, initialization of data structures, and generation of files which are later used by the other stages. It reads the input design and prepares the file for approximation, for example, by removing FrontEnd-specific annotations.

The standard FrontEnd implementation is called ``AnnotatedCandidates``, which is also the value to assign to the ``Input`` section's ``Method`` option to use this implementation.

AnnotatedCandidates
-------------------

The ``AnnotatedCandidates`` FrontEnd relies on annotations in the Verilog input design, marking Verilog modules as approximation candidates. To mark a module for approximation, a ``Key``, specified in the config. file, must be inserted in the input file between the module keyword and the module name. Additional parameters, following the ``Key``and framed by ``<<<`` and ``>>>``, can be used to specify the applied approximation methods and quality constraints for the particular module or candidate. The additional parameter annotation uses the :ref:`default CIRCA parameter syntax <config_circa>`.

.. todo:: Create link to parameter syntax documentation

Example module definition with ``Key = <<<APPROX_CAND>>>``:

 .. code-block:: verilog

    module <<<APPROX_CAND>>><<<WC:bound=20,step=2;appMethods:PS>>> Adder(in, cout);
    // Module content...
    endmodule

Configuration options
---------------------

:``Method``: ``AnnotatedCandidates``

:``Key``: The keyword used to mark a module as approximation candidate. Can have any string value which does not appear anywhere else in the input design file. Recommended value is ``<<<APPROX_CAND>>>``.

.. admonition:: Notes and restrictions

  * Candidates are generated from *Verilog modules*, not *instances*. Thus, parameters set for specific instances of the Verilog module are *ignored*. You may use parameters in the module; however, do not change these parameters for the instances.
  * The size of all primary input and output signals of the top-level module of the circuit and all marked modules must be an *absolute literal integer*, i.e., the size must be 1 or specified as ``[msb:lsb]`` where ``msb`` and ``lsb`` are integer numbers, *not parameters, localparams, or expressions* which resolve to an integer. Example:

     .. code-block:: verilog

        input clk;         // size 1, ok
        input [3:0] in1;   // size 4, ok
        input [4-1:0] in2; // expression, not ok
        parameter W = 3;
        output [W:0] out;  // parameter, not ok

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:ref:`Back to the User Guide <user_guide_built_ins>`