#include <netlist_traversal_decorator.h>

Collaboration diagram for hal::NetlistTraversalDecorator:

Public Member Functions
	NetlistTraversalDecorator (const Netlist &netlist)

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 , const u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , const 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 , const u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , const 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 , const u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , const 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 , const u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , const 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={}, std::unordered_map< const Net , std::set< Gate * >> *cache=nullptr) const

Result< std::set< Gate * > >	get_next_sequential_gates (const Gate gate, bool successors, const std::set< PinType > &forbidden_pins={}, std::unordered_map< const Net , std::set< Gate * >> *cache=nullptr) 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_next_combinational_gates (const Net net, bool successors, const std::set< PinType > &forbidden_pins={}, std::unordered_map< const Net , std::set< Gate * >> *cache=nullptr) const

Result< std::set< Gate * > >	get_next_combinational_gates (const Gate gate, bool successors, const std::set< PinType > &forbidden_pins={}, std::unordered_map< const Net , std::set< Gate * >> *cache=nullptr) 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 , const u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , const 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 , const u32 current_depth)> &exit_endpoint_filter=nullptr, const std::function< bool(const Endpoint , const u32 current_depth)> &entry_endpoint_filter=nullptr) const

Detailed Description

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

Definition at line 41 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 8 of file netlist_traversal_decorator.cpp.

Member Function Documentation

◆ get_next_combinational_gates() [1/2]

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

Starting from the given gate, traverse the netlist and return all combinational successor/predecessor gates. Continue traversal as long as further combinational gates are found and stop at gates that are not combinational. All combinational gates found during traversal are added to the result. Provide a cache to speed up traversal when calling this function multiple times on the same netlist.

Parameters

[in]	gate	- Start gate.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in,out]	cache	- An optional cache that can be used for better performance on repeated calls. Defaults to a `nullptr`.

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

Definition at line 653 of file netlist_traversal_decorator.cpp.

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

◆ get_next_combinational_gates() [2/2]

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

Starting from the given net, traverse the netlist and return all combinational successor/predecessor gates. Continue traversal as long as further combinational gates are found and stop at gates that are not combinational. All combinational gates found during traversal are added to the result. Provide a cache to speed up traversal when calling this function multiple times on the same netlist.

Parameters

[in]	net	- Start net.
[in]	successors	- Set `true` to get successors, set `false` to get predecessors.
[in,out]	cache	- An optional cache that can be used for better performance on repeated calls. Defaults to a `nullptr`.

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

Definition at line 549 of file netlist_traversal_decorator.cpp.

References hal::combinational, ERR, hal::Net::get_destinations(), hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), hal::Net::get_sources(), hal::Gate::get_type(), hal::BasePin< T >::get_type(), hal::GateType::has_property(), hal::Netlist::is_net_in_netlist(), test::n, net, and OK.

Referenced by get_next_combinational_gates().

◆ 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 *, const u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, const 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.

◆ 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 *, const u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, const 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. 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.

◆ 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 *, const u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, const 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.

◆ 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 *, const u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, const 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.

◆ 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 340 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 265 of file netlist_traversal_decorator.cpp.

References ERR, test_plugin::g, hal::Net::get_destinations(), hal::Net::get_sources(), hal::Netlist::is_net_in_netlist(), test::n, net, and OK.

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 = `{}`,
		std::unordered_map< const Net , std::set< Gate >> *	cache = `nullptr`
	)		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. Provide a cache to speed up traversal when calling this function multiple times on the same netlist using the same forbidden pins.

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.
[in,out]	cache	- An optional cache that can be used for better performance on repeated calls. Defaults to a `nullptr`.

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

Definition at line 480 of file netlist_traversal_decorator.cpp.

References ERR, hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), get_next_sequential_gates(), 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 = `{}`,
		std::unordered_map< const Net , std::set< Gate >> *	cache = `nullptr`
	)		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. Provide a cache to speed up traversal when calling this function multiple times on the same netlist using the same forbidden pins.

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.
[in,out]	cache	- An optional cache that can be used for better performance on repeated calls. Defaults to a `nullptr`.

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

Definition at line 367 of file netlist_traversal_decorator.cpp.

References ERR, hal::Net::get_destinations(), hal::Gate::get_fan_in_endpoints(), hal::Gate::get_fan_out_endpoints(), hal::Net::get_sources(), hal::Gate::get_type(), hal::BasePin< T >::get_type(), hal::GateType::has_property(), hal::Netlist::is_net_in_netlist(), test::n, net, OK, and hal::sequential.

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

◆ 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.

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

Definition at line 528 of file netlist_traversal_decorator.cpp.

References ERR, test_plugin::g, hal::Netlist::get_gates(), get_next_sequential_gates(), and OK.

◆ get_shortest_path()

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 *, const u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, const 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 incase of successs, an error otherwise.

Definition at line 813 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.

◆ 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 *, const u32 current_depth)> &	exit_endpoint_filter = `nullptr`,
		const std::function< bool(const Endpoint *, const 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 incase of success, an erro otherwise.

Definition at line 704 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.

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

/home/runner/work/hal/hal/include/hal_core/netlist/decorators/netlist_traversal_decorator.h
/home/runner/work/hal/hal/src/netlist/decorators/netlist_traversal_decorator.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ NetlistTraversalDecorator()

Member Function Documentation

◆ get_next_combinational_gates() [1/2]

◆ get_next_combinational_gates() [2/2]

◆ 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()

◆ get_shortest_path_distance()