transactron.utils package

Submodules

transactron.utils.assign module

class transactron.utils.assign.AssignType

Bases: Enum

ALL = 4
COMMON = 1
LHS = 2
RHS = 3
transactron.utils.assign.assign(lhs: amaranth.hdl._ast.Value | int | enum.Enum | amaranth.hdl._ast.ValueCastable | collections.abc.Mapping[str, AssignArg] | collections.abc.Mapping[int, AssignArg] | collections.abc.Sequence[AssignArg], rhs: amaranth.hdl._ast.Value | int | enum.Enum | amaranth.hdl._ast.ValueCastable | collections.abc.Mapping[str, AssignArg] | collections.abc.Mapping[int, AssignArg] | collections.abc.Sequence[AssignArg], *, fields: transactron.utils.assign.AssignType | collections.abc.Iterable[str | int] | collections.abc.Mapping[str | int, AssignFields] = AssignType.RHS, lhs_strict=False, rhs_strict=False) → Iterable[Assign]

Safe structured assignment.

This function recursively generates assignment statements for field-containing structures. This includes: Amaranth Views using StructLayout, Python dicts. In case of mismatching fields or bit widths, error is raised.

When both lhs and rhs are field-containing, assign generates assignment statements according to the value of the field parameter. If either of lhs or rhs is not field-containing, assign checks for the same bit width and generates a single assignment statement.

The bit width check is performed if:

  • Any of lhs or rhs is a View.

  • Both lhs and rhs have an explicitly defined shape (e.g. are a Signal, a field of a View).

Parameters
lhsView or Value-castable or dict

View, signal or dict being assigned.

rhsView or Value-castable or dict

View, signal or dict containing assigned values.

fieldsAssignType or Iterable or Mapping, optional

Determines which fields will be assigned. Possible values:

AssignType.COMMON

Only fields common to lhs and rhs are assigned.

AssignType.LHS

All fields in lhs are assigned. If one of them is not present in rhs, an exception is raised.

AssignType.RHS

All fields in rhs are assigned. If one of them is not present in lhs, an exception is raised.

AssignType.ALL

Assume that both structures have the same layouts. All fields present in lhs or rhs are assigned.

Mapping

Keys are field names, values follow the format for fields.

Iterable

Items are field names. For subfields, AssignType.ALL is assumed.

Returns
Iterable[Assign]

Generated assignment statements.

Raises
ValueError

If the assignment can’t be safely performed.

transactron.utils.data_repr module

transactron.utils.data_repr.align_down_to_power_of_two(num: int, power: int) → int

Rounds down a number to the given power of two.

Parameters
numint

The number to align.

powerint

The power of two to align to.

Returns
int

The aligned number.

transactron.utils.data_repr.align_to_power_of_two(num: int, power: int) → int

Rounds up a number to the given power of two.

Parameters
numint

The number to align.

powerint

The power of two to align to.

Returns
int

The aligned number.

transactron.utils.data_repr.average_dict_of_lists(d: Mapping[Any, Sized]) → float
transactron.utils.data_repr.bits_from_int(num: int, lower: int, length: int)

Returns [lower:lower`+`length) bits from integer num.

transactron.utils.data_repr.data_layout(val: amaranth.hdl._ast.Shape | amaranth.hdl._ast.ShapeCastable | int | range | type[enum.Enum]) → amaranth.lib.data.StructLayout | collections.abc.Iterable[tuple[str, 'ShapeLike | LayoutList']]
transactron.utils.data_repr.int_to_signed(x: int, xlen: int) → int

Converts a Python integer into its U2 representation.

Parameters
x: int

Signed Python integer.

xlenint

Bit width of x.

Returns
returnint

Representation of x in the U2 system.

transactron.utils.data_repr.layout_subset(layout: StructLayout, *, fields: set[str]) → StructLayout
transactron.utils.data_repr.make_hashable(val)
transactron.utils.data_repr.neg(x: int, xlen: int) → int

Computes the negation of a number in the U2 system.

Parameters
x: int

Number in U2 system.

xlenint

Bit width of x.

Returns
returnint

Negation of x in the U2 system.

transactron.utils.data_repr.signed_to_int(x: int, xlen: int) → int

Changes U2 representation into Python integer

Parameters
x: int

Number in U2 system.

xlenint

Bit width of x.

Returns
returnint

Representation of x as signed Python integer.

transactron.utils.debug_signals module

transactron.utils.debug_signals.auto_debug_signals(thing) → amaranth.hdl._ast.Signal | amaranth.hdl._rec.Record | amaranth.lib.data.View | collections.abc.Iterable[amaranth.hdl._ast.Signal | amaranth.hdl._rec.Record | amaranth.lib.data.View | collections.abc.Iterable[SignalBundle] | collections.abc.Mapping[str, SignalBundle]] | collections.abc.Mapping[str, amaranth.hdl._ast.Signal | amaranth.hdl._rec.Record | amaranth.lib.data.View | collections.abc.Iterable[SignalBundle] | collections.abc.Mapping[str, SignalBundle]]

Automatic debug signal generation.

Exposes class attributes with debug signals (Amaranth Signals, Records, Arrays and Elaboratables, Methods, classes which define debug_signals). Used for generating gtkw files in tests, for use in gtkwave.

transactron.utils.depcache module

class transactron.utils.depcache.DependentCache

Bases: object

Cache for classes, that depend on the DependentCache class itself.

Cached classes may accept one positional argument in the constructor, where this DependentCache class will be passed. Classes may define any number keyword arguments in the constructor and separate cache entry will be created for each set of the arguments.

Methods

get: T, **kwargs -> T

Gets class cls from cache. Caches cls reference if this is the first call for it. Optionally accepts kwargs for additional arguments in cls constructor.
__init__()
get(cls: Type[T], **kwargs) → T

transactron.utils.dependencies module

class transactron.utils.dependencies.DependencyContext

Bases: object

__init__(manager: DependencyManager)
classmethod get() → DependencyManager
stack: list[transactron.utils.dependencies.DependencyManager] = []
class transactron.utils.dependencies.DependencyKey

Bases: Generic[T, U], ABC

Base class for dependency keys.

Dependency keys are used to access dependencies in the DependencyManager. Concrete instances of dependency keys should be frozen data classes.

Parameters
lock_on_get: bool, default: True

Specifies if no new dependencies should be added to key if it was already read by get_dependency.

cache: bool, default: True

If true, result of the combine method is cached and subsequent calls to get_dependency will return the value in the cache. Adding a new dependency clears the cache.

empty_valid: bool, defaultFalse

Specifies if getting key dependency without any added dependencies is valid. If set to False, that action would cause raising KeyError.

cache: bool = True
abstract combine(data: list[T]) → U

Combine multiple dependencies with the same key.

This method is used to generate the value returned from get_dependency in the DependencyManager. It takes dependencies added to the key using add_dependency and combines them to a single result.

Different implementations of combine give different combining behavior for different kinds of keys.

empty_valid: bool = False
lock_on_get: bool = True
class transactron.utils.dependencies.DependencyManager

Bases: object

Dependency manager.

Tracks dependencies across the core.

__init__()
add_dependency(key: DependencyKey[T, Any], dependency: T) → None

Adds a new dependency to a key.

Depending on the key type, a key can have a single dependency or multple dependencies added to it.

dependency_provided(key: DependencyKey) → bool

Checks if any dependency for a key is provided (ignores empty_valid parameter)

get_dependency(key: DependencyKey[Any, U]) → U

Gets the dependency for a key.

The way dependencies are interpreted is dependent on the key type.

class transactron.utils.dependencies.ListKey

Bases: Generic[T], DependencyKey[T, list[T]]

Base class for list key.

List keys are used when there is an one-to-many relation between keys and dependecies. Provides list of dependencies.

combine(data: list[T]) → list[T]

Combine multiple dependencies with the same key.

This method is used to generate the value returned from get_dependency in the DependencyManager. It takes dependencies added to the key using add_dependency and combines them to a single result.

Different implementations of combine give different combining behavior for different kinds of keys.

empty_valid: bool = True
class transactron.utils.dependencies.SimpleKey

Bases: Generic[T], DependencyKey[T, T]

Base class for simple dependency keys.

Simple dependency keys are used when there is an one-to-one relation between keys and dependencies. If more than one dependency is added to a simple key, an error is raised.

Parameters
default_value: T

Specifies the default value returned when no dependencies are added. To enable it empty_valid must be True.

combine(data: list[T]) → T

Combine multiple dependencies with the same key.

This method is used to generate the value returned from get_dependency in the DependencyManager. It takes dependencies added to the key using add_dependency and combines them to a single result.

Different implementations of combine give different combining behavior for different kinds of keys.

default_value: T

transactron.utils.gen module

class transactron.utils.gen.GeneratedLog

Bases: LogRecordInfo

Information about a log record in the generated Verilog code.

Attributes
trigger_locationSignalHandle

The location of the trigger signal.

fields_locationlist[SignalHandle]

Locations of the log fields.

__init__(logger_name: str, level: int, format_str: str, location: tuple[str, int], trigger_location: list[str], fields_location: list[list[str]]) → None
fields_location: list[list[str]]
classmethod from_dict(kvs: Optional[Union[dict, list, str, int, float, bool]], *, infer_missing=False) → A
classmethod from_json(s: Union[str, bytes, bytearray], *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw) → A
classmethod schema(*, infer_missing: bool = False, only=None, exclude=(), many: bool = False, context=None, load_only=(), dump_only=(), partial: bool = False, unknown=None) → SchemaF[A]
to_dict(encode_json=False) → Dict[str, Optional[Union[dict, list, str, int, float, bool]]]
to_json(*, skipkeys: bool = False, ensure_ascii: bool = True, check_circular: bool = True, allow_nan: bool = True, indent: Optional[Union[int, str]] = None, separators: Optional[Tuple[str, str]] = None, default: Optional[Callable] = None, sort_keys: bool = False, **kw) → str
trigger_location: list[str]
class transactron.utils.gen.GenerationInfo

Bases: object

Various information about the generated circuit.

Attributes
metrics_locationdict[str, MetricInfo]

Mapping from a metric name to an object storing Verilog locations of its registers.

logslist[GeneratedLog]

Locations and metadata for all log records.

__init__(metrics_location: dict[str, transactron.utils.gen.MetricLocation], transaction_signals_location: dict[int, transactron.utils.gen.TransactionSignalsLocation], method_signals_location: dict[int, transactron.utils.gen.MethodSignalsLocation], profile_data: ProfileData, logs: list[transactron.utils.gen.GeneratedLog]) → None
static decode(file_name: str) → GenerationInfo

Loads the generation information from a JSON file.

encode(file_name: str)

Encodes the generation information as JSON and saves it to a file.

classmethod from_dict(kvs: Optional[Union[dict, list, str, int, float, bool]], *, infer_missing=False) → A
classmethod from_json(s: Union[str, bytes, bytearray], *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw) → A
logs: list[transactron.utils.gen.GeneratedLog]
method_signals_location: dict[int, transactron.utils.gen.MethodSignalsLocation]
metrics_location: dict[str, transactron.utils.gen.MetricLocation]
profile_data: ProfileData
classmethod schema(*, infer_missing: bool = False, only=None, exclude=(), many: bool = False, context=None, load_only=(), dump_only=(), partial: bool = False, unknown=None) → SchemaF[A]
to_dict(encode_json=False) → Dict[str, Optional[Union[dict, list, str, int, float, bool]]]
to_json(*, skipkeys: bool = False, ensure_ascii: bool = True, check_circular: bool = True, allow_nan: bool = True, indent: Optional[Union[int, str]] = None, separators: Optional[Tuple[str, str]] = None, default: Optional[Callable] = None, sort_keys: bool = False, **kw) → str
transaction_signals_location: dict[int, transactron.utils.gen.TransactionSignalsLocation]
class transactron.utils.gen.MetricLocation

Bases: object

Information about the location of a metric in the generated Verilog code.

Attributes
regsdict[str, SignalHandle]

The location of each register of that metric.

__init__(regs: dict[str, list[str]] = <factory>) → None
classmethod from_dict(kvs: Optional[Union[dict, list, str, int, float, bool]], *, infer_missing=False) → A
classmethod from_json(s: Union[str, bytes, bytearray], *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw) → A
regs: dict[str, list[str]]
classmethod schema(*, infer_missing: bool = False, only=None, exclude=(), many: bool = False, context=None, load_only=(), dump_only=(), partial: bool = False, unknown=None) → SchemaF[A]
to_dict(encode_json=False) → Dict[str, Optional[Union[dict, list, str, int, float, bool]]]
to_json(*, skipkeys: bool = False, ensure_ascii: bool = True, check_circular: bool = True, allow_nan: bool = True, indent: Optional[Union[int, str]] = None, separators: Optional[Tuple[str, str]] = None, default: Optional[Callable] = None, sort_keys: bool = False, **kw) → str
transactron.utils.gen.generate_verilog(elaboratable: Elaboratable, ports: Optional[list[amaranth.hdl._ast.Value]] = None, top_name: str = 'top') → tuple[str, transactron.utils.gen.GenerationInfo]

transactron.utils.idgen module

class transactron.utils.idgen.IdGenerator

Bases: object

__init__()

transactron.utils.transactron_helpers module

transactron.utils.transactron_helpers.async_mock_def_helper(tb, func: Callable[[...], T], arg: data.Const[StructLayout]) → T
transactron.utils.transactron_helpers.def_helper(description, func: Callable[[...], T], tp: type[U], arg: U, /, **kwargs) → T
transactron.utils.transactron_helpers.extend_layout(layout: StructLayout, *fields: tuple[str, amaranth.hdl._ast.Shape | amaranth.hdl._ast.ShapeCastable | int | range | type[enum.Enum] | list[tuple[str, ForwardRef('ShapeLike | LayoutList')]]]) → StructLayout
transactron.utils.transactron_helpers.from_method_layout(layout: amaranth.lib.data.StructLayout | collections.abc.Iterable[tuple[str, amaranth.hdl._ast.Shape | amaranth.hdl._ast.ShapeCastable | int | range | type[enum.Enum] | list[tuple[str, ForwardRef('ShapeLike | LayoutList')]]]]) → StructLayout
transactron.utils.transactron_helpers.get_caller_class_name(default: Optional[str] = None) → tuple[Optional[amaranth.hdl._ir.Elaboratable], str]
transactron.utils.transactron_helpers.get_src_loc(src_loc: int | tuple[str, int]) → tuple[str, int]
transactron.utils.transactron_helpers.longest_common_prefix(*seqs: Sequence[T]) → Sequence[T]
transactron.utils.transactron_helpers.make_layout(*fields: tuple[str, amaranth.hdl._ast.Shape | amaranth.hdl._ast.ShapeCastable | int | range | type[enum.Enum] | list[tuple[str, ForwardRef('ShapeLike | LayoutList')]]]) → StructLayout
transactron.utils.transactron_helpers.method_def_helper(method, func: Callable[[...], T], arg: View[StructLayout]) → T
transactron.utils.transactron_helpers.mock_def_helper(tb, func: Callable[[...], T], arg: Mapping[str, Any]) → T
transactron.utils.transactron_helpers.silence_mustuse(elaboratable: Elaboratable)

Module contents