#include <hal_core/netlist/decorators/netlist_traversal_decorator.h>

Collaboration diagram for hal::NetlistTraversalDecorator:

Public Member Functions
	NetlistTraversalDecorator (const Netlist &netlist)

Result< std::set< Gate * > >	get_gates (const Net net, TraversalDirection direction, const std::function< bool(const Gate )> &match, TraversalStop stop, u32 max_depth=0, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::set< Gate * > >	get_gates (const Gate gate, TraversalDirection direction, const std::function< bool(const Gate )> &match, TraversalStop stop, u32 max_depth=0, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::set< Gate * > >	get_next_matching_gates (const Net net, bool successors, const std::function< bool(const Gate )> &target_gate_filter, bool continue_on_match=false, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::set< Gate * > >	get_next_matching_gates (const Gate gate, bool successors, const std::function< bool(const Gate )> &target_gate_filter, bool continue_on_match=false, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::set< Gate * > >	get_next_matching_gates_until (const Net net, bool successors, const std::function< bool(const Gate )> &target_gate_filter, bool continue_on_mismatch=false, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::set< Gate * > >	get_next_matching_gates_until (const Gate gate, bool successors, const std::function< bool(const Gate )> &target_gate_filter, bool continue_on_mismatch=false, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::set< Gate * > >	get_next_matching_gates_until_depth (const Net net, bool successors, u32 max_depth, const std::function< bool(const Gate )> &target_gate_filter=nullptr) const

Result< std::set< Gate * > >	get_next_matching_gates_until_depth (const Gate gate, bool successors, u32 max_depth, const std::function< bool(const Gate )> &target_gate_filter=nullptr) const

Result< std::set< Gate * > >	get_next_sequential_gates (const Net *net, bool successors, const std::set< PinType > &forbidden_pins={}) const

Result< std::set< Gate * > >	get_next_sequential_gates (const Gate *gate, bool successors, const std::set< PinType > &forbidden_pins={}) const

Result< std::map< Gate , std::set< Gate > > >	get_next_sequential_gates_map (bool successors, const std::set< PinType > &forbidden_pins) const

Result< std::set< Gate * > >	get_combinational_cone (const Net *net, bool successors, const std::set< PinType > &forbidden_pins={}) const

Result< std::set< Gate * > >	get_combinational_cone (const Gate *gate, bool successors, const std::set< PinType > &forbidden_pins={}) const

Result< std::optional< u32 > >	get_shortest_path_distance (const Gate start_gate, const Gate end_gate, const PinDirection &direction, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::optional< std::vector< Gate * > > >	get_shortest_path (const Gate start_gate, const Gate end_gate, const PinDirection &direction, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::optional< std::vector< Gate * > > >	get_shortest_path (const Gate start_gate, const Module end_module, const PinDirection &direction, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::vector< std::vector< Gate * > > >	get_shortest_path (const Module start_module, const Module end_module, const PinDirection &direction, const std::function< bool(const Endpoint , u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , u32 current_depth)> &entry_endpoint_filter=nullptr) const

Result< std::vector< Gate * > >	get_gate_chain (Gate start_gate, const std::vector< const GatePin > &input_pins={}, const std::vector< const GatePin * > &output_pins={}, const std::function< bool(const Gate *)> &filter=nullptr) const

Result< std::vector< Gate * > >	get_complex_gate_chain (Gate start_gate, const std::vector< GateType > &chain_types, const std::map< GateType , std::vector< const GatePin >> &input_pins={}, const std::map< GateType , std::vector< const GatePin >> &output_pins={}, const std::function< bool(const Gate *)> &filter=nullptr) const

Result< std::vector< Net * > >	get_common_inputs (const std::vector< Gate * > &gates, u32 threshold=0) const

TraversalCache	make_traversal_cache (TraversalDirection direction, std::function< bool(const Gate )> match, TraversalStop stop, std::function< bool(const Endpoint )> exit_endpoint_filter=nullptr, std::function< bool(const Endpoint *)> entry_endpoint_filter=nullptr) const

Result< std::set< Gate * > >	get_gates (const Net *net, TraversalCache &cache) const

Result< std::set< Gate * > >	get_gates (const Gate *gate, TraversalCache &cache) const

Detailed Description

A netlist decorator that provides functionality to traverse the associated netlist without making any modifications.

Definition at line 134 of file netlist_traversal_decorator.h.

Constructor & Destructor Documentation

◆ NetlistTraversalDecorator()

hal::NetlistTraversalDecorator::NetlistTraversalDecorator ( const Netlist & netlist )

Construct new NetlistTraversalDecorator object.

Parameters

[in] netlist - The netlist to operate on.

Definition at line 12 of file netlist_traversal_decorator.cpp.

Member Function Documentation

◆ get_combinational_cone() [1/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_combinational_cone	(	const Gate *	gate,
		bool	successors,
		const std::set< PinType > &	forbidden_pins = `{}`
	)		const

Starting from the given gate, collect the combinational cone in the given direction, i.e., the combinational fan-out (successors = true) or fan-in (successors = false) of the gate. Continue traversal as long as further combinational gates are found and stop at gates that are not combinational, so that the cone extends up to (but not including) the sequential boundary. All combinational gates found during traversal are added to the result. Forbidden pins can be provided to, e.g., avoid the inclusion of logic in front of flip-flop control inputs. For repeated calls on the same netlist, seal the traversal into a reusable cache with make_traversal_cache and call get_gates with it instead.

Parameters

[in]	gate	- Start gate.
[in]	successors	- Set `true` to get the fan-out cone, set `false` to get the fan-in cone.
[in]	forbidden_pins	- Traversal stops at pins of these types, i.e., gates reached through such a pin are not part of the result. Defaults to an empty set.

Returns: The gates of the combinational cone on success, an error otherwise.

Definition at line 705 of file netlist_traversal_decorator.cpp.

References hal::at_mismatch, hal::combinational, ERR, ERR_APPEND, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), hal::Gate::get_id(), hal::Gate::get_name(), hal::Netlist::is_gate_in_netlist(), and OK.

◆ get_combinational_cone() [2/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_combinational_cone	(	const Net *	net,
		bool	successors,
		const std::set< PinType > &	forbidden_pins = `{}`
	)		const

Starting from the given net, collect the combinational cone in the given direction, i.e., the combinational fan-out (successors = true) or fan-in (successors = false) of the net. Continue traversal as long as further combinational gates are found and stop at gates that are not combinational, so that the cone extends up to (but not including) the sequential boundary. All combinational gates found during traversal are added to the result. Forbidden pins can be provided to, e.g., avoid the inclusion of logic in front of flip-flop control inputs. For repeated calls on the same netlist, seal the traversal into a reusable cache with make_traversal_cache and call get_gates with it instead.

Parameters

[in]	net	- Start net.
[in]	successors	- Set `true` to get the fan-out cone, set `false` to get the fan-in cone.
[in]	forbidden_pins	- Traversal stops at pins of these types, i.e., gates reached through such a pin are not part of the result. Defaults to an empty set.

Returns: The gates of the combinational cone on success, an error otherwise.

Definition at line 696 of file netlist_traversal_decorator.cpp.

References hal::at_mismatch, hal::combinational, and net.

◆ get_common_inputs()

Result< std::vector< Net * > > hal::NetlistTraversalDecorator::get_common_inputs	(	const std::vector< Gate * > &	gates,
		u32	threshold = `0`
	)		const

Get the nets that are inputs to at least threshold of the given gates.

Shared inputs across a group of gates typically indicate a shared control signal, so this is a cheap way to test whether a set of gates belongs together. A threshold of 0 requires a net to feed every single one of the gates. Nets driven by GND or VCC gates do not count.

Parameters

[in]	gates	- The gates to inspect.
[in]	threshold	- The number of gates a net has to feed. `0` to require all of them. Defaults to `0`.

Returns: The common input nets on success, an error otherwise.

Definition at line 338 of file netlist_traversal_decorator.cpp.

References ERR, hal::Gate::get_id(), hal::Gate::get_name(), hal::Gate::get_predecessors(), hal::Netlist::is_gate_in_netlist(), net, and OK.

◆ get_complex_gate_chain()

Result< std::vector< Gate * > > hal::NetlistTraversalDecorator::get_complex_gate_chain	(	Gate *	start_gate,
		const std::vector< GateType * > &	chain_types,
		const std::map< GateType , std::vector< const GatePin >> &	input_pins = `{}`,
		const std::map< GateType , std::vector< const GatePin >> &	output_pins = `{}`,
		const std::function< bool(const Gate *)> &	filter = `nullptr`
	)		const

Find a chain of gates that repeats the given sequence of gate types, starting at the given gate.

Parameters

[in]	start_gate	- The gate to start from.
[in]	chain_types	- The gate types the chain repeats, in order.
[in]	input_pins	- The input pins to follow, per gate type. Defaults to all of them.
[in]	output_pins	- The output pins to follow, per gate type. Defaults to all of them.
[in]	filter	- An optional filter a gate has to pass to be part of the chain.

Returns: The gates of the chain in order on success, an error otherwise.

Definition at line 1198 of file netlist_traversal_decorator.cpp.

References ERR, hal::Endpoint::get_gate(), hal::Gate::get_id(), hal::Netlist::get_id(), hal::Gate::get_name(), hal::Gate::get_netlist(), hal::Endpoint::get_pin(), hal::Gate::get_predecessors(), hal::Gate::get_successors(), hal::Gate::get_type(), log_debug, and OK.

◆ get_gate_chain()

Result< std::vector< Gate * > > hal::NetlistTraversalDecorator::get_gate_chain	(	Gate *	start_gate,
		const std::vector< const GatePin * > &	input_pins = `{}`,
		const std::vector< const GatePin * > &	output_pins = `{}`,
		const std::function< bool(const Gate *)> &	filter = `nullptr`
	)		const

Find a chain of gates of the same type, starting at the given gate and following its output pins.

Parameters

[in]	start_gate	- The gate to start from.
[in]	input_pins	- The input pins to follow. Defaults to all of them.
[in]	output_pins	- The output pins to follow. Defaults to all of them.
[in]	filter	- An optional filter a gate has to pass to be part of the chain.

Returns: The gates of the chain in order on success, an error otherwise.

Definition at line 1075 of file netlist_traversal_decorator.cpp.

References ERR, hal::Endpoint::get_gate(), hal::Gate::get_id(), hal::Netlist::get_id(), hal::Gate::get_name(), hal::Gate::get_netlist(), hal::Gate::get_successors(), hal::Gate::get_type(), and log_debug.

◆ get_gates() [1/4]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_gates	(	const Gate *	gate,
		TraversalCache &	cache
	)		const

Traverse the netlist from the given gate, collecting the gates that the cache's traversal collects.

The parameters of the walk live in the cache, see make_traversal_cache, and results are shared through it: what an earlier call worked out is not walked again.

Parameters

[in]	gate	- The gate to start from.
[in]	cache	- The cache holding the traversal and its results.

Returns: The gates that were collected on success, an error otherwise.

Definition at line 406 of file netlist_traversal_decorator.cpp.

References hal::both, ERR, ERR_APPEND, hal::forward, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), get_gates(), hal::Gate::get_id(), hal::Gate::get_name(), hal::Netlist::is_gate_in_netlist(), and OK.

◆ get_gates() [2/4]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_gates	(	const Gate *	gate,
		TraversalDirection	direction,
		const std::function< bool(const Gate *)> &	match,
		TraversalStop	stop,
		u32	max_depth = `0`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Traverse the netlist from the given gate, collecting the gates that match accepts.

This is the traversal that the other functions of this decorator are written in terms of. What distinguishes them from one another is stop, which says where the walk halts relative to the gates being looked for, see TraversalStop.

Parameters

[in]	gate	- The gate to start from.
[in]	direction	- The direction to traverse in.
[in]	match	- The condition a gate has to meet to be collected.
[in]	stop	- Where to stop traversing, relative to the gates that `match` accepts.
[in]	max_depth	- The maximum number of gates to traverse through, counted from 1 for the direct neighbours of the start. `0` for no limit.
[in]	exit_endpoint_filter	- Condition that has to hold to leave a gate through a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Condition that has to hold to enter a gate through a successor/predecessor endpoint.

Returns: The gates that were collected on success, an error otherwise.

Definition at line 142 of file netlist_traversal_decorator.cpp.

References hal::backward, hal::both, direction, ERR, ERR_APPEND, hal::forward, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), get_gates(), hal::Gate::get_id(), hal::Gate::get_name(), hal::Netlist::is_gate_in_netlist(), and OK.

◆ get_gates() [3/4]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_gates	(	const Net *	net,
		TraversalCache &	cache
	)		const

Traverse the netlist from the given net, collecting the gates that the cache's traversal collects.

The parameters of the walk live in the cache, see make_traversal_cache, and results are shared through it: what an earlier call worked out is not walked again.

Parameters

[in]	net	- The net to start from.
[in]	cache	- The cache holding the traversal and its results.

Returns: The gates that were collected on success, an error otherwise.

Definition at line 391 of file netlist_traversal_decorator.cpp.

References hal::both, ERR, hal::forward, and net.

◆ get_gates() [4/4]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_gates	(	const Net *	net,
		TraversalDirection	direction,
		const std::function< bool(const Gate *)> &	match,
		TraversalStop	stop,
		u32	max_depth = `0`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Traverse the netlist from the given net, collecting the gates that match accepts.

This is the traversal that the other functions of this decorator are written in terms of. What distinguishes them from one another is stop, which says where the walk halts relative to the gates being looked for, see TraversalStop.

Parameters

[in]	net	- The net to start from.
[in]	direction	- The direction to traverse in.
[in]	match	- The condition a gate has to meet to be collected.
[in]	stop	- Where to stop traversing, relative to the gates that `match` accepts.
[in]	max_depth	- The maximum number of gates to traverse through, counted from 1 for the direct neighbours of the start. `0` for no limit.
[in]	exit_endpoint_filter	- Condition that has to hold to leave a gate through a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Condition that has to hold to enter a gate through a successor/predecessor endpoint.

Returns: The gates that were collected on success, an error otherwise.

Definition at line 16 of file netlist_traversal_decorator.cpp.

References hal::at_match, hal::at_mismatch, hal::backward, hal::both, direction, ERR, hal::forward, hal::Net::get_destinations(), hal::Net::get_sources(), hal::Netlist::is_net_in_netlist(), net, and OK.

Referenced by hal::boolean_influence::get_ff_dependency_matrix(), get_gates(), get_next_matching_gates(), get_next_matching_gates_until(), get_next_matching_gates_until_depth(), and get_next_sequential_gates_map().

◆ get_next_matching_gates() [1/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_matching_gates	(	const Gate *	gate,
		bool	successors,
		const std::function< bool(const Gate *)> &	target_gate_filter,
		bool	continue_on_match = `false`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the target_gate_filter evaluates to true. Traverse over gates that do not meet the target_gate_filter condition. Stop traversal if (1) continue_on_match is false the target_gate_filter evaluates to true, (2) the exit_endpoint_filter evaluates to false on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the entry_endpoint_filter evaluates to false on a successor/predecessor endpoint (i.e., when entering the next gate during traversal). Both the entry_endpoint_filter and the exit_endpoint_filter may be omitted.

Parameters

[in]	gate	- Start gate.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	target_gate_filter	- Filter condition that must be met for the target gates.
[in]	continue_on_match	- Set `true` to continue even if `target_gate_filter` evaluated to `true`, `false` otherwise. Defaults to `false`.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: The next gates fulfilling the target gate filter condition on success, an error otherwise.

Definition at line 220 of file netlist_traversal_decorator.cpp.

References ERR, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), get_next_matching_gates(), hal::Netlist::is_gate_in_netlist(), and OK.

◆ get_next_matching_gates() [2/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_matching_gates	(	const Net *	net,
		bool	successors,
		const std::function< bool(const Gate *)> &	target_gate_filter,
		bool	continue_on_match = `false`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the target_gate_filter evaluates to true. Traverse over gates that do not meet the target_gate_filter condition.

Equivalent to get_gates with a TraversalStop of at_match, or of never when continue_on_match is set. Stop traversal if (1) continue_on_match is false the target_gate_filter evaluates to true, (2) the exit_endpoint_filter evaluates to false on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the entry_endpoint_filter evaluates to false on a successor/predecessor endpoint (i.e., when entering the next gate during traversal). Both the entry_endpoint_filter and the exit_endpoint_filter may be omitted.

Parameters

[in]	net	- Start net.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	target_gate_filter	- Filter condition that must be met for the target gates.
[in]	continue_on_match	- Set `true` to continue even if `target_gate_filter` evaluated to `true`, `false` otherwise. Defaults to `false`.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: The next gates fulfilling the target gate filter condition on success, an error otherwise.

Definition at line 209 of file netlist_traversal_decorator.cpp.

References hal::at_match, hal::backward, hal::forward, get_gates(), net, and hal::never.

Referenced by hal::module_identification::find_neighboring_registers(), and get_next_matching_gates().

◆ get_next_matching_gates_until() [1/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_matching_gates_until	(	const Gate *	gate,
		bool	successors,
		const std::function< bool(const Gate *)> &	target_gate_filter,
		bool	continue_on_mismatch = `false`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the target_gate_filter evaluates to true. Continue traversal independent of whatever target_gate_filter evaluates to. Stop traversal if (1) continue_on_mismatch is false the target_gate_filter evaluates to false, (2) the exit_endpoint_filter evaluates to false on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the entry_endpoint_filter evaluates to false on a successor/predecessor endpoint (i.e., when entering the next gate during traversal). Both entry_endpoint_filter and the exit_endpoint_filter may be omitted.

Parameters

[in]	gate	- Start gate.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	target_gate_filter	- Filter condition that must be met for the target gates.
[in]	continue_on_mismatch	- Set `true` to continue even if `target_gate_filter` evaluated to `false`, `false` otherwise. Defaults to `false`.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: The next gates fulfilling the target gate filter condition on success, an error otherwise.

Definition at line 268 of file netlist_traversal_decorator.cpp.

References ERR, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), get_next_matching_gates_until(), hal::Netlist::is_gate_in_netlist(), and OK.

◆ get_next_matching_gates_until() [2/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_matching_gates_until	(	const Net *	net,
		bool	successors,
		const std::function< bool(const Gate *)> &	target_gate_filter,
		bool	continue_on_mismatch = `false`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the target_gate_filter evaluates to true. Continue traversal independent of whatever target_gate_filter evaluates to. Stop traversal if (1) continue_on_mismatch is false the target_gate_filter evaluates to false, (2) the exit_endpoint_filter evaluates to false on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the entry_endpoint_filter evaluates to false on a successor/predecessor endpoint (i.e., when entering the next gate during traversal). Both entry_endpoint_filter and the exit_endpoint_filter may be omitted.

Parameters

[in]	net	- Start net.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	target_gate_filter	- Filter condition that must be met for the target gates.
[in]	continue_on_mismatch	- Set `true` to continue even if `target_gate_filter` evaluated to `false`, `false` otherwise. Defaults to `false`.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: The next gates fulfilling the target gate filter condition on success, an error otherwise.

Definition at line 257 of file netlist_traversal_decorator.cpp.

References hal::at_mismatch, hal::backward, hal::forward, get_gates(), net, and hal::never.

Referenced by get_next_matching_gates_until().

◆ get_next_matching_gates_until_depth() [1/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_matching_gates_until_depth	(	const Gate *	gate,
		bool	successors,
		u32	max_depth,
		const std::function< bool(const Gate *)> &	target_gate_filter = `nullptr`
	)		const

Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the target_gate_filter evaluates to true. Continue traversal independent of whatever target_gate_filter evaluates to. Stop traversal if the specified depth is reached. The current depth is counted starting at 1 for the direct successors/predecessors of the provided gate. For a depth of 0, all gates between the start gate and the global netlist outputs will be traversed. The target_gate_filter may be omitted in which case all traversed gates will be returned.

Parameters

[in]	gate	- Start gate.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	max_depth	- The maximum depth for netlist traversal starting from the start gate.
[in]	target_gate_filter	- Filter condition that must be met for the target gates.

Returns: The next gates fulfilling the target gate filter condition on success, an error otherwise.

Definition at line 312 of file netlist_traversal_decorator.cpp.

References ERR, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), get_next_matching_gates_until_depth(), hal::Netlist::is_gate_in_netlist(), and OK.

◆ get_next_matching_gates_until_depth() [2/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_matching_gates_until_depth	(	const Net *	net,
		bool	successors,
		u32	max_depth,
		const std::function< bool(const Gate *)> &	target_gate_filter = `nullptr`
	)		const

Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the target_gate_filter evaluates to true. Continue traversal independent of whatever target_gate_filter evaluates to. Stop traversal if the specified depth is reached. The current depth is counted starting at 1 for the destinations of the provided net. For a depth of 0, all nets between the start gate and the global netlist outputs will be traversed. The target_gate_filter may be omitted in which case all traversed gates will be returned.

Parameters

[in]	net	- Start net.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	max_depth	- The maximum depth for netlist traversal starting from the start net.
[in]	target_gate_filter	- Filter condition that must be met for the target gates.

Returns: The next gates fulfilling the target gate filter condition on success, an error otherwise.

Definition at line 305 of file netlist_traversal_decorator.cpp.

References hal::backward, hal::forward, get_gates(), net, and hal::never.

Referenced by get_next_matching_gates_until_depth().

◆ get_next_sequential_gates() [1/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_sequential_gates	(	const Gate *	gate,
		bool	successors,
		const std::set< PinType > &	forbidden_pins = `{}`
	)		const

Starting from the given gate, traverse the netlist and return only the next layer of sequential successor/predecessor gates. Traverse over gates that are not sequential until a sequential gate is found. Stop traversal at all sequential gates, but only adds those to the result that have not been reached through a pin of one of the forbidden types. For repeated calls on the same netlist, seal the traversal into a reusable cache with make_traversal_cache and call get_gates with it instead.

Parameters

[in]	gate	- Start gate.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	forbidden_pins	- Sequential gates reached through these pins will not be part of the result. Defaults to an empty set.

Returns: The next sequential gates on success, an error otherwise.

Definition at line 639 of file netlist_traversal_decorator.cpp.

References hal::at_match, ERR, ERR_APPEND, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), hal::Gate::get_id(), hal::Gate::get_name(), hal::Netlist::is_gate_in_netlist(), and OK.

◆ get_next_sequential_gates() [2/2]

Result< std::set< Gate * > > hal::NetlistTraversalDecorator::get_next_sequential_gates	(	const Net *	net,
		bool	successors,
		const std::set< PinType > &	forbidden_pins = `{}`
	)		const

Starting from the given net, traverse the netlist and return only the next layer of sequential successor/predecessor gates. Traverse over gates that are not sequential until a sequential gate is found. Stop traversal at all sequential gates, but only adds those to the result that have not been reached through a pin of one of the forbidden types. For repeated calls on the same netlist, seal the traversal into a reusable cache with make_traversal_cache and call get_gates with it instead.

Parameters

[in]	net	- Start net.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	forbidden_pins	- Sequential gates reached through these pins will not be part of the result. Defaults to an empty set.

Returns: The next sequential gates on success, an error otherwise.

Definition at line 633 of file netlist_traversal_decorator.cpp.

References hal::at_match, and net.

◆ get_next_sequential_gates_map()

Result< std::map< Gate , std::set< Gate > > > hal::NetlistTraversalDecorator::get_next_sequential_gates_map	(	bool	successors,
		const std::set< PinType > &	forbidden_pins
	)		const

Get the next sequential gates for all sequential gates in the netlist by traversing through remaining logic (e.g., combinational logic). Compute a map from a sequential gate to all its successors. Stop traversal at all sequential gates, but only adds those to the result that have not been reached through a pin of one of the forbidden types.

Parameters

[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in]	forbidden_pins	- Sequential gates reached through these pins will not be part of the result. Defaults to an empty set.

Returns: A map from each sequential gate to all its sequential successors on success, an error otherwise.

Definition at line 672 of file netlist_traversal_decorator.cpp.

References hal::at_match, hal::backward, ERR, hal::forward, hal::Netlist::get_gates(), get_gates(), make_traversal_cache(), and OK.

◆ get_shortest_path() [1/3]

Result< std::optional< std::vector< Gate * > > > hal::NetlistTraversalDecorator::get_shortest_path	(	const Gate *	start_gate,
		const Gate *	end_gate,
		const PinDirection &	direction,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Find the shortest path (i.e., the result set with the lowest number of gates) that connects the start gate with the end gate. The gate where the search started from will be the first in the result vector, the end gate will be the last. If there is no such path an empty optional is returned. If there is more than one path with the same length only the first one is returned.

Parameters

[in]	start_gate	- The gate to start from.
[in]	end_gate	- The gate to connect to.
[in]	direction	- The direction to search in. Can be PinDirection::input, PinDirection::output or PinDirection::inout to search both directions and return the shorter one.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: An optional vector of gates that connect the start with end gate on success, an error otherwise.

Definition at line 982 of file netlist_traversal_decorator.cpp.

References direction, and ERR.

Referenced by get_shortest_path().

◆ get_shortest_path() [2/3]

Result< std::optional< std::vector< Gate * > > > hal::NetlistTraversalDecorator::get_shortest_path	(	const Gate *	start_gate,
		const Module *	end_module,
		const PinDirection &	direction,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Find the shortest path (i.e., the result set with the lowest number of gates) that connects the start gate with any gate of the given module. The start gate will be the first in the result vector, the gate reached within the module the last. If there is no such path an empty optional is returned. If there is more than one path with the same length only the first one is returned. A start gate that already belongs to the module yields a path consisting of that gate alone.

Parameters

[in]	start_gate	- The gate to start from.
[in]	end_module	- The module to connect to. Gates of its submodules count as belonging to it.
[in]	direction	- The direction to search in. Can be PinDirection::input, PinDirection::output or PinDirection::inout to search both directions and return the shorter one.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: An optional vector of gates that connect the start gate with the module on success, an error otherwise.

Definition at line 997 of file netlist_traversal_decorator.cpp.

References direction, ERR, hal::Netlist::get_gate_by_id(), hal::Module::get_gates(), hal::Gate::get_id(), hal::Gate::get_netlist(), and OK.

◆ get_shortest_path() [3/3]

Result< std::vector< std::vector< Gate * > > > hal::NetlistTraversalDecorator::get_shortest_path	(	const Module *	start_module,
		const Module *	end_module,
		const PinDirection &	direction,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Find every shortest path (i.e., the result sets with the lowest number of gates) that connects the start module with the end module. There may be more than one such path, so every path of that length is returned; each runs from a gate of the start module to a gate of the end module. If there is no such path an empty vector is returned.

Parameters

[in]	start_module	- The module to start from. Gates of its submodules count as belonging to it.
[in]	end_module	- The module to connect to. Gates of its submodules count as belonging to it.
[in]	direction	- The direction to search in. Can be PinDirection::input, PinDirection::output or PinDirection::inout to search both directions and return the shorter one.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: A vector of the shortest paths connecting the two modules on success, an error otherwise.

Definition at line 1024 of file netlist_traversal_decorator.cpp.

References direction, ERR, ERR_APPEND, hal::Module::get_gates(), hal::Module::get_id(), hal::Gate::get_name(), hal::Module::get_name(), get_shortest_path(), and OK.

◆ get_shortest_path_distance()

Result< std::optional< u32 > > hal::NetlistTraversalDecorator::get_shortest_path_distance	(	const Gate *	start_gate,
		const Gate *	end_gate,
		const PinDirection &	direction,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, u32 current_depth)> &	entry_endpoint_filter = `nullptr`
	)		const

Find the length of shortest path (i.e., the result set with the lowest number of gates) that connects the start gate with the end gate. If there is no such path an empty optional is returned. Computing only the shortest distance to a gate is faster than computing the shortest path, since it does not have to keep track of the path to reach each gate.

Parameters

[in]	start_gate	- The gate to start from.
[in]	end_gate	- The gate to connect to.
[in]	direction	- The direction to search in. Can be PinDirection::input, PinDirection::output or PinDirection::inout to search both directions and return the shorter one.
[in]	exit_endpoint_filter	- Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.

Returns: An optional unsigned integer representing the shortest distance between the start and end gate on success, an error otherwise.

Definition at line 738 of file netlist_traversal_decorator.cpp.

References direction, hal::enum_to_string(), ERR, hal::Netlist::get_gate_by_id(), hal::Gate::get_id(), hal::Gate::get_name(), hal::Gate::get_netlist(), hal::inout, hal::input, OK, and hal::output.

◆ make_traversal_cache()

TraversalCache hal::NetlistTraversalDecorator::make_traversal_cache	(	TraversalDirection	direction,
		std::function< bool(const Gate *)>	match,
		TraversalStop	stop,
		std::function< bool(const Endpoint *)>	exit_endpoint_filter = `nullptr`,
		std::function< bool(const Endpoint *)>	entry_endpoint_filter = `nullptr`
	)		const

Create a cache for one specific traversal, to be handed to get_gates in place of the traversal's parameters.

The direction must be TraversalDirection::forward or backward; a cache cannot hold both directions at once. The endpoint filters receive no depth, and there is no depth limit, as either would make the cached answers depend on how a net was reached.

Parameters

[in]	direction	- The direction to traverse in.
[in]	match	- The condition a gate has to meet to be collected.
[in]	stop	- Where to stop traversing, relative to the gates that `match` accepts.
[in]	exit_endpoint_filter	- Condition that has to hold to leave a gate through a fan-in/out endpoint.
[in]	entry_endpoint_filter	- Condition that has to hold to enter a gate through a successor/predecessor endpoint.

Returns: The cache.

Definition at line 382 of file netlist_traversal_decorator.cpp.

References direction.

Referenced by hal::boolean_influence::get_ff_dependency_matrix(), and get_next_sequential_gates_map().

The documentation for this class was generated from the following files:

include/hal_core/netlist/decorators/netlist_traversal_decorator.h
src/netlist/decorators/netlist_traversal_decorator.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ NetlistTraversalDecorator()

Member Function Documentation

◆ get_combinational_cone() [1/2]

◆ get_combinational_cone() [2/2]

◆ get_common_inputs()

◆ get_complex_gate_chain()

◆ get_gate_chain()

◆ get_gates() [1/4]

◆ get_gates() [2/4]

◆ get_gates() [3/4]

◆ get_gates() [4/4]

◆ get_next_matching_gates() [1/2]

◆ get_next_matching_gates() [2/2]

◆ get_next_matching_gates_until() [1/2]

◆ get_next_matching_gates_until() [2/2]

◆ get_next_matching_gates_until_depth() [1/2]

◆ get_next_matching_gates_until_depth() [2/2]

◆ get_next_sequential_gates() [1/2]

◆ get_next_sequential_gates() [2/2]

◆ get_next_sequential_gates_map()

◆ get_shortest_path() [1/3]

◆ get_shortest_path() [2/3]

◆ get_shortest_path() [3/3]

◆ get_shortest_path_distance()

◆ make_traversal_cache()