chipflow.utils
==============

.. py:module:: chipflow.utils

.. autoapi-nested-parse::

   Core utility functions for ChipFlow

   This module provides core utilities used throughout the chipflow library.



Exceptions
----------

.. autoapisummary::

   chipflow.utils.ChipFlowError


Functions
---------

.. autoapisummary::

   chipflow.utils.get_cls_by_reference
   chipflow.utils.ensure_chipflow_root
   chipflow.utils.get_src_loc
   chipflow.utils.compute_invert_mask
   chipflow.utils.top_components
   chipflow.utils.get_software_builds


Module Contents
---------------

.. py:exception:: ChipFlowError

   Bases: :py:obj:`Exception`


   Base exception for ChipFlow errors


.. py:function:: get_cls_by_reference(reference, context)

   Dynamically import and return a class by its module:class reference string.

   :param reference: String in format "module.path:ClassName"
   :param context: Description of where this reference came from (for error messages)

   :returns: The class object

   :raises ChipFlowError: If module or class cannot be found


.. py:function:: ensure_chipflow_root()

   Ensure CHIPFLOW_ROOT environment variable is set and return its path.

   If CHIPFLOW_ROOT is not set, sets it to the current working directory.
   Also ensures the root is in sys.path.

   :returns: Path to the chipflow root directory


.. py:function:: get_src_loc(src_loc_at = 0)

   Get the source location (filename, line number) of the caller.

   :param src_loc_at: Number of frames to go back (0 = immediate caller)

   :returns: Tuple of (filename, line_number)


.. py:function:: compute_invert_mask(invert_list)

   Compute a bit mask for signal inversion from a list of boolean invert flags.

   :param invert_list: List of booleans indicating which bits should be inverted

   :returns: Integer mask where set bits indicate positions to invert


.. py:function:: top_components(config)

   Return the top level components for the design, as configured in ``chipflow.toml``.

   :param config: The parsed chipflow configuration

   :returns: Dictionary mapping component names to instantiated Component objects

   :raises ChipFlowError: If component references are invalid or instantiation fails


.. py:function:: get_software_builds(m, component)

   Extract software build information from a component's interfaces.

   :param m: Module containing the component
   :param component: Name of the component

   :returns: Dictionary of interface names to SoftwareBuild objects