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.

   Args:
       reference: String in format "module.path:ClassName"
       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.

   Args:
       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.

   Args:
       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``.

   Args:
       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.

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

   Returns:
       Dictionary of interface names to SoftwareBuild objects