FABulous.fabric_generator.parser.parse_hdl
==========================================

.. py:module:: FABulous.fabric_generator.parser.parse_hdl

.. autoapi-nested-parse::
   Contains functions for processing BEL related information from HDL files.



Classes
-------


Functions
---------

.. py:function:: belMapProcessing(module_info)

Extract and transform BEL mapping attributes in `YosysModule`.

   :param module_info: A dictionary containing the module's attributes, including
                       potential BEL mapping information.
   :type module_info: dict

   :returns: Dictionary containing the parsed bel mapping information.
   :rtype: dic

.. py:function:: parseBelFile(filename, belPrefix = '')

Parse a Verilog or VHDL BEL file and return related information of the BEL.

   The function will also parse and record all the FABulous attributes
   which all start with:

       (* FABulous, <type>, ... *)

   The <type> can be one the following:

   * **BelMap**
   * **EXTERNAL**
   * **SHARED_PORT**
   * **GLOBAL**
   * **CONFIG_PORT**
   * **SHARED_ENABLE**
   * **SHARED_RESET**

   The **BelMap** attribute will specify the bel mapping for the bel.
   This attribute should be placed before the start of the module.
   The bel mapping is then used for generating the bitstream specification.
   Each of the entry in the attribute will have the following format::

   <name> = <value>

   ``<name>`` is the name of the feature and ``<value>`` will be the
   bit position of the feature. ie. ``INIT=0`` will specify that the feature
   ``INIT`` is located at bit 0.
   Since a single feature can be mapped to multiple bits, this is currently done by
   specifying multiple entries for the same feature.
   This will be changed in the future.
   The bit specification is done in the following way::

       INIT_a_1=1, INIT_a_2=2, ...

   The name of the feature will be converted to ``INIT_a[1]``, ``INIT_a[2]``
   for the above example. This is necessary
   because  Verilog does not allow square brackets as part of the attribute name.

   **EXTERNAL** attribute will notify FABulous to put the pin in the top module during
   the fabric generation.

   **SHARED_PORT** attribute will notify FABulous this the pin is shared between
   multiple bels. Attribute need to go with
   the **EXTERNAL** attribute.

   **GLOBAL** attribute will notify FABulous to stop parsing any pin after this
   attribute.

   **CONFIG_PORT** attribute will notify FABulous the port is for configuration.

   .. rubric:: Example

   .. rubric:: Verilog

   (* FABulous, BelMap,
   single_bit_feature=0, //single bit feature, single_bit_feature=0
   multiple_bits_0=1, //multiple bit feature bit0, multiple_bits[0]=1
   multiple_bits_1=2 //multiple bit feature bit1, multiple_bits[1]=2
   *)
   module exampleModule (
       externalPin,
       normalPin1,
       normalPin2,
       sharedPin,
       globalPin);
       (* FABulous, EXTERNAL *) input externalPin;
       input normalPin;
       (* FABulous, EXTERNAL, SHARED_PORT *) input sharedPin;
       (* FABulous, GLOBAL) input globalPin;
       output normalPin2; //do not get parsed
       ...

   :param filename: The filename of the bel file.
   :type filename: str
   :param belPrefix: The bel prefix provided by the CSV file. Defaults to "".
   :type belPrefix: str, optional)

   :returns:

             - List of Bel Internal ports (belName, IO).
             - List of Bel External ports (belName, IO).
             - List of Bel Config ports (belName, IO).
             - List of Bel Shared ports (belName, IO).
             - Number of configuration bits in the bel.
             - Whether the bel has UserCLK.
             - Bel config bit mapping as a dict {port_name: bit_number}.
   :rtype: Tuple containing

   :raises ValueError: File not found
   :raises ValueError: No permission to access the file
   :raises ValueError: Bel file contains no or more than one module