.. rst-class:: break_before

Open Logic
==========

What is Open Logic?
-------------------

`Open Logic <https://github.com/open-logic/open-logic>`_ is a comprehensive VHDL standard library for FPGA projects that aims to be for HDL projects what stdlib is for C/C++ projects. It is a collection of commonly used, reusable, and vendor-independent components provided under a permissive open-source license (LGPL with exceptions for FPGA usage).

.. note::
    Open Logic is automatically included with every new XiBIF project. You don't need to install or configure it separately - it's ready to use out of the box.


Library Structure
-----------------

Open Logic is organized into four main areas:

* **Base**  
    Basic logic components for device internal logic. This forms the foundation that other areas depend on.

* **AXI**  
    Components for AXI4/AXI4-Lite/AXI4-Stream interfaces.

* **Interface (intf)**  
    Logic for device external interfaces.

* **Fixed Point (fix)**  
    Fixed-point mathematics with bit-accurate models and co-simulation support. This area requires the ``en_cl_fix`` third-party library which is also included.

Available Components
~~~~~~~~~~~~~~~~~~~~

Open Logic provides a wide range of components including:

* **Clock and Reset Management** - Clock crossing, reset synchronizers
* **FIFOs and Memories** - Various FIFO implementations, RAM controllers
* **Mathematical Functions** - Arithmetic units, trigonometric functions
* **Signal Processing** - Filters, converters, data path components
* **Communication Interfaces** - UART, SPI, I2C implementations
* **AXI Infrastructure** - AXI masters, slaves, interconnects

.. tip::
    Browse the complete `Entity List <https://github.com/open-logic/open-logic/blob/main/doc/EntityList.md>`_ to see all available components with detailed documentation.

Example Usage
~~~~~~~~~~~~~

Here's a simple example of using an Open Logic FIFO in your VHDL design:

.. code-block:: vhdl

    library ieee;
    use ieee.std_logic_1164.all;
    use ieee.numeric_std.all;
    
    library olo;
    use olo.olo_base_pkg_math.all;
    use olo.olo_base_pkg_logic.all;


    entity my_design is
        port (
            clk_i     : in  std_logic;
            rst_i     : in  std_logic;
            data_i    : in  std_logic_vector(31 downto 0);
            valid_i   : in  std_logic;
            ready_o   : out std_logic;
            data_o    : out std_logic_vector(31 downto 0);
            valid_o   : out std_logic;
            ready_i   : in  std_logic
        );
    end entity;

    architecture behavioral of my_design is
    begin
        
        -- Open Logic FIFO instance
        i_fifo : entity work.olo_base_fifo_sync
            generic map (
                Width_g     => 32,
                Depth_g     => 1024
            )
            port map (
                Clk         => clk_i,
                Rst         => rst_i,
                In_Data     => data_i,
                In_Valid    => valid_i,
                In_Ready    => ready_o,
                Out_Data    => data_o,
                Out_Valid   => valid_o,
                Out_Ready   => ready_i
            );
            
    end architecture;

Additional Resources
--------------------

* `Open Logic GitHub Repository <https://github.com/open-logic/open-logic>`_
* `Complete Entity List <https://github.com/open-logic/open-logic/blob/main/doc/EntityList.md>`_
* `Vivado Tutorial <https://github.com/open-logic/open-logic/blob/main/doc/tutorials/VivadoTutorial.md>`_
* `Contributing Guide <https://github.com/open-logic/open-logic/blob/main/Contributing.md>`_