.. rst-class:: break_before

Quickstart
==========

This quickstart guide provides the essential commands to get you up and running with XiBIF quickly. For detailed information, please refer to the linked sections.

.. _quickstart-installation:

Installation
------------

Create a virtual environment:

.. code-block:: console

    python -m venv .venv-xibif

Activate the virtual environment:

.. code-block:: console

    .venv-xibif\Scripts\activate  # Windows
    source .venv-xibif/bin/activate  # Linux/macOS

Install XiBIF using pip:

.. code-block:: console

    pip install xibif

Verify the installation:

.. code-block:: console

    xibif -v

For detailed installation instructions including prerequisites and virtual environment setup, see :doc:`../tutorials/installation`.

.. _quickstart-creating-project:

Creating a New Project
----------------------

Create a new XiBIF project with:

.. code-block:: console

    xibif new -n <project_name> -p <project_path> -b <board> -x <xilinx_path> -v <xilinx_version>

**Example:**

.. code-block:: console

    xibif new -n MyProject -p D:\projects\myproject -b zedboard -x C:\Xilinx -v 2024.2

**Quick Reference:**

- ``-n``: Project name
- ``-p``: Project path
- ``-b``: Board (e.g., zedboard, ...)
- ``-x``: Xilinx installation path
- ``-v``: Xilinx version

For more details, see :doc:`../tutorials/hardware-design-flow`.

.. _quickstart-building:

Building Your Project
---------------------

Build the complete project (hardware + software):

.. code-block:: console

    xibif build

This command performs synthesis, place-and-route, bitstream generation, and software compilation. The result is a ``BOOT.bin`` file in ``hw/results/`` that can be copied to an SD card.

**Build Hardware Only:**

.. code-block:: console

    xibif build --to vivado:reportTiming

**Build Software Only:**

.. code-block:: console

    xibif build --from vitis:update

**Build Specific Stages:**

.. code-block:: console

    xibif build --stage vivado:synthesize
    xibif build --stage vivado:bitstream vivado:export vitis:update vitis:build vitis:export

**Build Stage Ranges:**

.. code-block:: console

    xibif build --from vivado:synthesize --to vivado:bitstream

For more information on the build process, see :doc:`../tutorials/hardware-design-flow`.

.. _quickstart-flashing:

Flashing the FPGA
-----------------

Flash the bitstream to a running FPGA (non-persistent):

.. code-block:: console

    xibif flash

For more details, see :doc:`../tutorials/hardware-design-flow`.

.. _quickstart-simulation:

Simulating Your Design
----------------------

Generate a testbench for your VHDL file:

.. code-block:: console

    xibif testbench -f <my_file.vhd> -c <clock_signal> -rn <reset_signal>

**Example:**

.. code-block:: console

    xibif testbench -f adder.vhd -c clk_in -rn resetn_in

This generates testbenches in ``hw/tb/`` and ``hw/tb/vunit/`` with clock and reset generators.

Run all simulations using VUnit:

.. code-block:: console

    xibif simulation

**Run Specific Test:**

.. code-block:: console

    xibif simulation -t <test_name>

**List Available Tests:**

.. code-block:: console

    xibif simulation -l

**Debug with GUI:**

.. code-block:: console

    xibif simulation -g

For detailed simulation setup and VUnit usage, see :doc:`../tutorials/simulation`.

.. _quickstart-connecting:

Connecting to Your FPGA
-----------------------

In your Python script:

.. code-block:: python

    from xibif_connection.api import XibifConnection

    # Create connection
    board = XibifConnection(ip="192.168.1.10", uuid=0xDEAD_CAFE)
    board.connect()

    # Read/write registers
    board.write(address, data)
    data = board.read(address)

    # Stream data
    board.write_stream(data_array)
    data = board.read_stream()

    # Close connection
    board.disconnect()

For network configuration and connection details, see :doc:`../tutorials/network` and :doc:`../tutorials/writing-software`.

.. _quickstart-registers:

Working with Registers
----------------------

Use the generated register map for easy register access:

.. code-block:: python

    from regs import RegMap

    regs = RegMap(connection)

    # Write to register
    regs.register_1 = 0x1234

    # Write to bitfield
    regs.register_1_bf.field_1 = 1

    # Read from register
    value = regs.register_2

    # Read from bitfield
    field_value = regs.register_2.field_1

For detailed register usage and generation, see :doc:`../tutorials/register-generation` and :doc:`../tutorials/writing-software`.

.. _quickstart-xilinx-tools:

Opening Xilinx Tools
--------------------

Open Vivado with your project:

.. code-block:: console

    xibif start vivado

Open Vitis with your project:

.. code-block:: console

    xibif start vitis

Start the hardware server:

.. code-block:: console

    xibif start hw_server

.. _quickstart-help:

Getting Help
------------

View all available commands:

.. code-block:: console

    xibif --help

View help for a specific command:

.. code-block:: console

    xibif build --help
    xibif new --help

.. _quickstart-next-steps:

Next Steps
----------

Now that you know the basics, explore these topics for more in-depth knowledge:

- :doc:`../tutorials/hardware-design-flow` - Complete hardware workflow
- :doc:`../tutorials/simulation` - Testing your design with VUnit
- :doc:`../tutorials/register-generation` - Creating custom registers
- :doc:`../tutorials/axi-stream` - Working with streaming data
- :doc:`../tutorials/status-control` - Status and control interfaces
- :doc:`../overview/zynq` - Understanding the Zynq architecture
- :doc:`../code/cli` - Command Line Interface reference
- :doc:`../appendix/troubleshooting` - Common issues and solutions