hwtLib.abstract package¶
A package of abstract components (components which needs to have some methods implemented before use) and other utilities.
Subpackages¶
Submodules¶
hwtLib.abstract.addressStepTranslation module¶
- class hwtLib.abstract.addressStepTranslation.AddressStepTranslation(src_addr_step: int = 8, dst_addr_step: int = 8)[source]¶
Bases:
object
- Variables
align_bits – number of bits on source/destination address which are addressing in a single word or other address
src_addr_step – how many bits is addressing one unit of src_addr_sig
dst_addr_step – how many bits is addressing one unit of dst_addr_sig
hwtLib.abstract.busBridge module¶
hwtLib.abstract.busEndpoint module¶
- class hwtLib.abstract.busEndpoint.BusEndpoint(structTemplate, intfCls=None, shouldEnterFn=None)[source]¶
Bases:
Unit
Abstract unit
Delegate request from bus to fields of structure (fields are represented by various interfaces) write has higher priority
- Note
implementation is usually address decoder
- __init__(structTemplate, intfCls=None, shouldEnterFn=None)[source]¶
- Parameters
structTemplate – instance of HStruct which describes address space of this endpoint
intfCls – class of bus interface which should be used
shouldEnterFn – function(root_t, structFieldPath) return (shouldEnter, shouldUse) where shouldEnter is flag that means iterator over this interface should look inside of this actual object and shouldUse flag means that this field should be used (to create interface)
- static _defaultShouldEnterFn(root: HdlType, field_path: Tuple[Union[str, int]])[source]¶
Default method which resolves how the parts of input data type should be represented on interface level.
- _getAddrStep() int [source]¶
- Returns
how many bits does 1 address unit addresses, (e.g. AXI -> 8b, index to uint32_t[N] -> 32)
- _getWordAddrStep() int [source]¶
- Returns
how many address units is one word on bus (e.g. 32b AXI -> 4)
- _mkFieldInterface(structIntf: StructIntf, field: HStructField)[source]¶
Instantiate field interface for fields in structure template of this endpoint
- Returns
interface for specified field
- connectByInterfaceMap(interfaceMap: IntfMap)[source]¶
Connect “decoded” struct interface to interfaces specified in interface map
- connect_directly_mapped_read(ar_addr: RtlSignal, r_data: RtlSignal, default_r_data_drive)[source]¶
Connect the RegCntrl.din interfaces to a bus
- connect_directly_mapped_write(aw_addr: RtlSignal, w_data: RtlSignal, en: RtlSignal)[source]¶
Connect the RegCntrl.dout interfaces to a bus
- classmethod fromInterfaceMap(interfaceMap)[source]¶
Generate converter by struct data type specified by interface map
- Parameters
interfaceMap –
hwt.interfaces.intf_map.HTypeFromIntfMap()
- propagateAddr(src_addr_sig: RtlSignal, src_addr_step: int, dst_addr_sig: RtlSignal, dst_addr_step: int, transTmpl: TransTmpl)[source]¶
- Parameters
src_addr_sig – input signal with address
src_addr_step – how many bits is addressing one unit of src_addr_sig
dst_addr_sig – output signal for address
dst_addr_step – how many bits is addressing one unit of dst_addr_sig
transTmpl – TransTmpl which has meta-informations about this address space transition
hwtLib.abstract.busInterconnect module¶
- class hwtLib.abstract.busInterconnect.AUTO_ADDR[source]¶
Bases:
object
constant which means that address should be picked automatically
- class hwtLib.abstract.busInterconnect.BusInterconnect(hdl_name_override: Optional[str] = None)[source]¶
Bases:
Unit
Abstract class of bus interconnects
- Variables
~.m – HObjList of master interfaces
~.s – HObjList of slave interfaces
- class hwtLib.abstract.busInterconnect.BusInterconnectUtils[source]¶
Bases:
object
- classmethod _extract_separable_group(mi: int, seen_m: Set[int], masters_connected_to: List[Set[int]], slaves_connected_to: List[Set[int]])[source]¶
Transitive enclosure of master/stalave ports on connected relation (Extract a group of all ports which are somehow connected to each other)
hwtLib.abstract.busStaticRemap module¶
- class hwtLib.abstract.busStaticRemap.BusStaticRemap(hdl_name_override: Optional[str] = None)[source]¶
Bases:
Unit
Abstract class for component which remaps memory regions on bus interfaces
- Variables
~.MEM_MAP – list of tuples (addr_from, size, addr_to) for each memory region on second interface
~.m – slave interface of first interface class where master should be connected
~.s – slave interface of second interface class where master slave be connected
hwtLib.abstract.componentBuilder module¶
- class hwtLib.abstract.componentBuilder.AbstractComponentBuilder(parent: Unit, srcInterface: Union[Interface, HObjList], name: Optional[str] = None, master_to_slave: bool = True)[source]¶
Bases:
object
Helper class which simplifies instantiation of commonly used components with configuration based on input/output interface
- Variables
~.compId – used for sequential number of components
~.lastComp – last builded component
~.end – last interface of data-path
- Attention
input port is taken from self.end
- __init__(parent: Unit, srcInterface: Union[Interface, HObjList], name: Optional[str] = None, master_to_slave: bool = True)[source]¶
- Parameters
parent – unit in which will be all units created by this builder instantiated
name – prefix for all instantiated units
srcInterface – start of data-path
master_to_slave – if True the circuit is build in natural direction (master to slave, input to output) othervise it is build in reverse direction
hwtLib.abstract.debug_bus_monitor module¶
- class hwtLib.abstract.debug_bus_monitor.DebugBusMonitor(bus_cls, bus_endpoint_cls)[source]¶
Bases:
Unit
This component is similar to ILA/ChipScope/SignalTAP but it is not connected to internal JTAG, but to a specified interface. This component generates an address decoder and connect all specified interfaces to a service bus. It also stores the names and bit widths of original interfaces in a ROM in order to display them later in test application. This component also supports for snapshots of values by a generic trigger method, transaction counters etc.
- Note
addressspace size depends on how much data is actually monitored. But it has fixed structure.
Example of meta_memory JSON format:
- build_meta_memory(monitored_data: List[DebugBusMonitorDataRecord])[source]¶
- build_meta_memory_json(monitored_data: List[DebugBusMonitorDataRecord], data_ids: Dict[DebugBusMonitorDataRecord, int], offset: int)[source]¶
- register(intf: Interface, name: Optional[str] = None, cdc: bool = False, trigger: Optional[RtlSignal] = None, add_reg: bool = False)[source]¶
- Parameters
intf – an interface to monitor
name – name override
cdc – if True instantiate Clock domain crossing to synchronize input data to clock domain of this component
trigger – an optional signal which triggers the snapshot of this interface
add_reg – if True an register is added between input and bus interface
- Note
if cdc is set to True the trigger has to be synchonezed to a clock clock domain of intf
- class hwtLib.abstract.debug_bus_monitor.DebugBusMonitorDataRecord(intf: Interface, name: str, cdc: bool, trigger: RtlSignal, add_reg: bool)[source]¶
Bases:
object
- add_children(c: DebugBusMonitorDataRecord)[source]¶
- add_link(dst: DebugBusMonitorDataRecord)[source]¶
hwtLib.abstract.discoverAddressSpace module¶
- class hwtLib.abstract.discoverAddressSpace.AddressSpaceProbe(topIntf, getMainSigFn, offset=0)[source]¶
Bases:
object
An object which can be used to discover an address space of an interface. Discovery is made by walking on address signal.
hwtLib.abstract.hwExceptionCtx module¶
- class hwtLib.abstract.hwExceptionCtx.ExceptionHandleInterface(exception: InHwError, masterDir=DIRECTION.OUT, loadConfig=True)[source]¶
Bases:
HandshakeSync
- __init__(exception: InHwError, masterDir=DIRECTION.OUT, loadConfig=True)[source]¶
This constructor is called when constructing new interface, it is usually done manually while creating
hwt.synthesizer.unit.Unit
or automatically while extracting interfaces from UnitWithSoure- Parameters
masterDir – direction which this interface should have for master
multiplyedBy – this can be instance of integer or Param, this mean the interface is array of the interfaces where multiplyedBy is the size
loadConfig – do load config in __init__
- class hwtLib.abstract.hwExceptionCtx.HwExceptionCtx(parent: Unit, name='raise')[source]¶
Bases:
object
An object which handles hardware exceptions.
- Attention
exception handling requires a clock and reset signal to be present on parent
hwt.synthesizer.unit.Unit
instance.
- _Unit_makePublicIntfPrivateInImpl(intf: ExceptionHandleInterface)[source]¶
- _Unit_registerPublicIntfInImpl(intf: ExceptionHandleInterface, name: str)[source]¶
- hw_catch(exception_cls: Optional[Union[Type[InHwError], Tuple[Type[InHwError], ...]]] = None) List[Tuple[InHwError, ExceptionHandleInterface]] [source]¶
Catch all uncatched exceptions by exception class.
- Parameters
exception_cls – An class on exceptions which should be catched (An exception is catched if its class is a subclass of exception_cls).
- Note
Catching exception means getting IO for exception handling in this context. You need to drive all interfaces and possibly re-raise for those which should not be catched.
- Returns
List of tuples (exception, interface) for every uncatched exception in current scope (includes children). (Due to parallel nature of hardware it is a list and exceptions may be raised simulately.)
- hw_raise(exception: InHwError, pending_flag: Optional[RtlSignalBase] = None, raising_flag: Optional[RtlSignalBase] = None)[source]¶
Construct a logic to raise an exception in generated hardware. This creates a flag and IO for exception handling status.
- Parameters
pending_flag – An optional flag which should be set to 1 if exception was raised in some previous clock cycle an it has not beed catched yet.
raising_flag – An optional flag which should be set to 1 if exception exception is beeing raised in this clock cycle.
- Attention
The arguments specified in the exception has to remain stable until the excetion is handled.
- Returns
An expression which triggers the exception handling.
- propagate()[source]¶
Propagate uncatched exceptions from this
hwt.synthesizer.unit.Unit
instance and its children to IO of thishwt.synthesizer.unit.Unit
instance.- Note
The exception is considered uncached if its rd signal is not driven.
hwtLib.abstract.monitorIntf module¶
- class hwtLib.abstract.monitorIntf.MonitorIntf(template_interface)[source]¶
Bases:
Interface
Interfaces same as template interface, but with all signals as an input
- __init__(template_interface)[source]¶
This constructor is called when constructing new interface, it is usually done manually while creating
hwt.synthesizer.unit.Unit
or automatically while extracting interfaces from UnitWithSoure- Parameters
masterDir – direction which this interface should have for master
multiplyedBy – this can be instance of integer or Param, this mean the interface is array of the interfaces where multiplyedBy is the size
loadConfig – do load config in __init__
- class hwtLib.abstract.monitorIntf.MonitorIntfReg(intfCls: Type[MonitorIntf])[source]¶
Bases:
Unit
- __init__(intfCls: Type[MonitorIntf])[source]¶
- class hwtLib.abstract.monitorIntf.MonitorIntfVldSynced(template_interface)[source]¶
Bases:
VldSynced
- __init__(template_interface)[source]¶
This constructor is called when constructing new interface, it is usually done manually while creating
hwt.synthesizer.unit.Unit
or automatically while extracting interfaces from UnitWithSoure- Parameters
masterDir – direction which this interface should have for master
multiplyedBy – this can be instance of integer or Param, this mean the interface is array of the interfaces where multiplyedBy is the size
loadConfig – do load config in __init__
- class hwtLib.abstract.monitorIntf.MonitorIntfVldSyncedCdc(template_interface)[source]¶
Bases:
VldSyncedCdc
- hwtLib.abstract.monitorIntf._connect_MonitorIntf(src: MonitorIntf, dst)[source]¶
- hwtLib.abstract.monitorIntf._connect_to_MonitorIntf(src, dst: MonitorIntf)[source]¶
- hwtLib.abstract.monitorIntf.connect_MonitorIntf(src: MonitorIntf, dst)[source]¶
Connect signal by signal and ignore the directions of struct interface (check only direction of low level signals)
- hwtLib.abstract.monitorIntf.connect_to_MonitorIntf(src, dst: MonitorIntf)[source]¶
Connect signal by signal and ignore the directions of struct interface (check only direction of low level signals)
hwtLib.abstract.sim_ram module¶
- exception hwtLib.abstract.sim_ram.AllocationError[source]¶
Bases:
Exception
Exception which says that requested allocation can not be performed
- class hwtLib.abstract.sim_ram.SimRam(cellSize, parent=None)[source]¶
Bases:
object
Dense memory for simulation purposes with data pump interfaces
- Variables
~.data – memory dict
- __init__(cellSize, parent=None)[source]¶
- Parameters
cellWidth – width of items in memory
clk – clk signal for synchronization
parent – parent instance of SimRam (memory will be shared with this instance)
- _getArray(offset, transTmpl)[source]¶
- Parameters
offset – global offset of this transTmpl (and struct)
transTmpl – instance of TransTmpl which specifies items in array
- _getStruct(offset, transTmpl)[source]¶
- Parameters
offset – global offset of this transTmpl (and struct)
transTmpl – instance of TransTmpl which specifies items in struct
- calloc(num, size, keepOut=None, initValues=None) int [source]¶
Allocates a block of memory for an array of num elements, each of them size bytes long, and initializes all its bits to zero.
- Parameters
num – Number of elements to allocate.
size – Size of each element.
keepOut – optional memory spacing between this memory region and lastly allocated (number of bit between last allocated segment to avoid)
initValues – iterable of word values to init memory with
- Returns
address (byte step) of allocated memory
- getBits(start, end, sign)[source]¶
Gets value of bits between selected range from memory
- Parameters
start – bit address of start of bit of bits
end – bit address of first bit behind bits
- Returns
instance of BitsVal (derived from SimBits type) which contains copy of selected bits
- hwtLib.abstract.sim_ram.reshapedInitItems(actualCellSize, requestedCellSize, values)[source]¶
Convert array item size and items cnt while size of array remains unchanged
- Parameters
actualCellSize – actual size of item in array
requestedCellSize – requested size of item in array
values – input array
- Returns
generator of new items of specified characteristic
hwtLib.abstract.streamBuilder module¶
- class hwtLib.abstract.streamBuilder.AbstractStreamBuilder(parent: Unit, srcInterface: Union[Interface, HObjList], name: Optional[str] = None, master_to_slave: bool = True)[source]¶
Bases:
AbstractComponentBuilder
- Note
see
AbstractComponentBuilder
- Attention
this is just abstract class unit classes has to be specified in concrete implementation
- Variables
~.FifoCls – FIFO unit class
~.FifoAsyncCls – asynchronous FIFO (FIFO with separate clock per port) unit class
~.JoinSelectCls – select order based join unit class
~.JoinFairCls – round robin based join unit class
~.JoinPrioritizedCls – priority based join unit class
~.RegCls – register unit class
~.RegCdcCls – Clock domain crossing register unit class
~.ResizerCls – resizer unit class (used to change data width of an interface)
~.SplitCopyCls – copy based split unit class
~.SplitSelectCls – select order based split unit class (demultiplexer)
~.SplitFairCls – round robin based split unit class
~.SplitPrioritizedCls – priority based split unit class
- FifoAsyncCls = NotImplemented¶
- FifoCls = NotImplemented¶
- JoinFairCls = NotImplemented¶
- JoinPrioritizedCls = NotImplemented¶
- JoinSelectCls = NotImplemented¶
- RegCls = NotImplemented¶
- ResizerCls = NotImplemented¶
- SplitCopyCls = NotImplemented¶
- SplitFairCls = NotImplemented¶
- SplitPrioritizedCls = NotImplemented¶
- SplitSelectCls = NotImplemented¶
- _genericInstance(unit_cls, name, set_params=<function AbstractStreamBuilder.<lambda>>, update_params=True, propagate_clk_rst=True)[source]¶
Instantiate generic component and connect basics
- Parameters
unit_cls – class of unit which is being created
name – name for unit_cls instance
set_params – function which updates parameters as is required (parameters are already shared with self.end interface)
- classmethod _join(joinCls, parent, srcInterfaces, name, configAs, extraConfigFn)[source]¶
Create builder from many interfaces by joining them together
- Parameters
joinCls – join component class which should be used
parent – unit where builder should place components
srcInterfacecs – sequence of interfaces which should be joined together (lower index = higher priority)
configureAs – interface or another object which configuration should be applied
extraConfigFn – function which is applied on join unit in configuration phase (can be None)
- buff(items: int = 1, latency: Union[None, int, Tuple[int, int]] = None, delay: Optional[int] = None, init_data: tuple = ())[source]¶
Use registers and FIFOs to create buffer of specified parameters :note: if items <= latency registers are used else FIFO is used
- Parameters
items – number of items in buffer
latency – latency of buffer (number of clk ticks required to get data from input to input)
delay – delay of buffer (number of clk ticks required to get data to buffer)
init_data – a reset value of buffer (data is transfered after reset) if items=1 and interface has just data:uint8_t signal the init_data will be in format ((0,),)
- Note
delay can be used as synchronization method or to solve timing related problems because it will split valid signal path
- Note
if latency or delay is None the most optimal value is used
- buff_cdc(clk, rst, items=1)[source]¶
Instantiate a CDC (Clock Domain Crossing) buffer or AsyncFifo on selected interface
- Note
if items==1 CDC clock synchronization register is used if items>1 asynchronous FIFO is used
- classmethod join_fair(parent, srcInterfaces, name=None, configAs=None, exportSelected=False)[source]¶
create builder from fairly joined interfaces (round robin for input select)
- Parameters
exportSelected – if True join component will have handshaked interface with index of selected input
- Note
other parameters same as in .AbstractStreamBuilder._join
- classmethod join_prioritized(parent, srcInterfaces, name=None, configAs=None, extraConfigFn=None)[source]¶
create builder from fairly joined interfaces (round robin for input select)
- Note
other parameters same as in .AbstractStreamBuilder._join
- split_copy(noOfOutputs)[source]¶
Clone input data to all outputs
- Parameters
noOfOutputs – number of output interfaces of the split
- split_copy_to(*outputs)[source]¶
Same like split_copy, but outputs are automatically connected
- Parameters
outputs – ports on which should be outputs of split component connected to
- split_fair(noOfOutputs, exportSelected=False)[source]¶
Create a round robin selector with number of outputs specified by noOfOutputs
- Parameters
noOfOutputs – number of outputs of multiplexer
exportSelected – if is True split component will have interface “selectedOneHot” of type VldSynced wich will have one hot index of selected item
- split_fair_to(*outputs, exportSelected=False)[source]¶
Same like split_fair, but outputs are automatically connected
- Parameters
outputs – ports on which should be outputs of split component connected to
exportSelected – if is True split component will have interface “selectedOneHot” of type VldSynced which will have one hot index of selected item
- split_prioritized(noOfOutputs)[source]¶
data from input is send to output which is ready and has highest priority from all ready outputs
- Parameters
noOfOutputs – number of output interfaces of the fork
- split_prioritized_to(*outputs)[source]¶
Same like split_prioritized, but outputs are automatically connected
- Parameters
outputs – ports on which should be outputs of split component connected to
- split_select(outputSelSignalOrSequence, noOfOutputs)[source]¶
Create a demultiplexer with number of outputs specified by noOfOutputs
- Parameters
noOfOutputs – number of outputs of multiplexer
outputSelSignalOrSequence – handshaked interface (onehot encoded) to control selected output or sequence of output indexes which should be used (will be repeated)
hwtLib.abstract.template_configured module¶
- hwtLib.abstract.template_configured.HdlType_separate(t: HdlType, do_separate_query: Callable[[HdlType], bool]) Generator[Tuple[bool, HdlType], None, None] [source]¶
Split HStruct type hierachy on the specified fields to multiple type definitions.
- class hwtLib.abstract.template_configured.TemplateConfigured(structT: HdlType, tmpl: Optional[TransTmpl] = None, frames: Optional[List[FrameTmpl]] = None)[source]¶
Bases:
object
Class with functions for extracting metadata from frame template/HdlType. Used for resolving of data mapping between abstract type and physical interface.
- __init__(structT: HdlType, tmpl: Optional[TransTmpl] = None, frames: Optional[List[FrameTmpl]] = None)[source]¶
- Parameters
structT – instance of HStruct used as template for this frame If name is None no input port is generated and space is filled with invalid values, little-endian encoding, supported types of interfaces are: Handshaked, Signal can be also instance of FrameTmpl
tmpl – instance of TransTmpl for this structT
frames – list of FrameTmpl instances for this tmpl
- Note
if tmpl and frames are None they are resolved from structT parseTemplate
- chainFrameWords() Generator[Tuple[int, List[Union[TransPart, ChoicesOfFrameParts]], bool], None, None] [source]¶