.. index::
    AIT user config file

.. _ait-user_config_file:

AIT user configuration file
=============================

AIT behaviour can be fine-tuned by overridding some configuration values using the ``--user_config`` and passing a user-provided JSON file.
The values specified in the file overrides any configuration done via AIT parameters.

Current supported configuration:

- Defining placement per accelerator instance
- Defining memory interface connection per data interface
- Disabling data interfaces
- Marking data interfaces for debug
- Defining register slices pipeline stages per accelerator instance

.. note::
    It is not mandatory to define every configuration possible for each accelerator, instance or interface in the design.
    If a configuration is not defined by the user configuration file, it will either take the value passed by an AIT parameter or the default one.


.. _ait-user_config_file-placement:

placement
^^^^^^^^^

In order to define placement for an accelerator instance, the key ``placement`` has to be placed inside the instance object of the accelerator that wants to be placed.

.. code-block:: json

    {
        "accs": {
            "dotproduct": {
                "instances": {
                    "0": {
                        "placement": "0"
                    },
                    "1": {
                        "placement": "1"
                    }
                }
            }
        }
    }

This will constrain instance 0 of ``dotproduct`` accelerator to the SLR0 and instance 1 to the SLR1.

Accelerator instances without placement defined will be automatically managed by Vivado.

.. _ait-user_config_file-dst:

dst
^^^

The memory interface where an accelerator instance data interface will be connected can be specified with the key ``dst`` inside the interfaces object.

.. code-block:: json

    {
        "accs": {
            "dotproduct": {
                "instances": {
                    "0": {
                        "interfaces": {
                            "v1": {
                                "dst": "2"
                            }
                        }
                    },
                    "1": {
                        "interfaces": {
                            "v1": {
                                "dst": "None"
                            },
                            "result": {
                                "dst": "0"
                            }
                        }
                    }
                }
            }
        }
    }

This will connect data interface ``v1`` of instance 0 of ``dotproduct`` accelerator to the memory interface ``2``, data interface ``result`` of instance 1 to memory interface ``0``, while data interface ``v1`` of instance 1 will be left dangling.
Data interfaces without ``dst`` defined will be connected automatically to a memory interface following a least-occupied policy.

.. _ait-user_config_file-debug:

debug
^^^^^

Data interfaces can be marked for debug and connected to an ILA automatically with the key ``debug`` inside the interfaces object.

.. code-block:: json

    {
        "accs": {
            "dotproduct": {
                "instances": {
                    "0": {
                        "interfaces": {
                            "v1": {
                                "debug": "True"
                            }
                        }
                    },
                    "1": {
                        "interfaces": {
                            "v1": {
                                "debug": "True"
                            },
                            "result": {
                                "dst": "False"
                            }
                        }
                    }
                }
            }
        }
    }

This will mark for debug data interfaces ``v1`` of instances 0 and 1 of ``dotproduct`` and connect them to an ILA.
No action will be taken for data interfaces without ``debug`` defined or defined as ``False``.

.. _ait-user_config_file-regslice_pipeline_stages:

regslice_pipeline_stages
^^^^^^^^^^^^^^^^^^^^^^^^

The number of pipeline stages created for each section of an SLR-crossing register slice can be configured with the key ``regslice_pipeline_stages`` for each accelerator instance.

.. code-block:: json

    {
        "accs": {
            "dotproduct": {
                "instances": {
                    "0": {
                        "regslice_pipeline_stages": "2:3:4"
                    },
                    "1": {
                        "regslice_pipeline_stages": ":auto:1"
                    }
                }
            }
        }
    }

This will configure the register slices affecting instance ``0`` of ``dotproduct`` as having 2 pipeline stages in the source section, 3 in the middle and 4 in the destination one.
Register slices of instance ``1`` of the ``dotproduct`` accelerator the following way: default (or the value passed to AIT by the ``--regslice_pipeline_stages`` parameter) for the source section, ``auto`` for the middle one (meaning that Vivado will automatically decide the number of stages) and 1 for the destination section.