P4::P4Tools Namespace Reference

Namespaces
namespace	ControlPlaneState
namespace	TraceEvents
	This file defines explicit types of trace events extended from the generic trace class.

Classes
class	AbstractExecutionState
	Represents state of execution after having reached a program point. More...
class	AbstractP4cTool
class	AbstractP4cToolOptions
class	AbstractRepCheckedNode
class	ArchSpec
	Specifies a canonical representation of the target pipeline as documented in P4 code. More...
class	CompileContext
	A compilation context for P4Tools that provides a custom compiler configuration. More...
class	CompilerConfiguration
class	CompilerResult
class	CompilerTarget
	Encapsulates the details of invoking the P4 compiler for a target device and architecture. More...
class	ConvertStructExpr
class	ConvertVarbits
class	ExtendedCallGraph
struct	FormatOptions
	Defines common formatting options. More...
class	HSIndexToMember
	The main class for finding non-concrete header stack indices. More...
struct	InheritedCompilerOptionSpec
class	MaskBuilder
class	MidEnd
class	Model
class	NamespaceContext
	Represents a stack of namespaces. More...
class	P4Constants
class	P4ProgramDCGCreator
	The main class for building control flow DCG. More...
class	ReachabilityEngine
class	ReachabilityEngineState
	The main data for reachability engine. More...
class	SmithOptions
class	SymbolicEnv
class	Taint
class	TaintPropagator
class	Target
class	TraceEvent
	An event in a trace of the execution of a P4 program. More...
class	Utils
	General utility functions that are not present in the compiler framework. More...
class	Z3Solver
	A Z3-based implementation of AbstractSolver. Encapsulates a z3::solver and a z3::context. More...
class	Z3SolverAccessor
class	Z3Translator
	Translates P4 expressions into Z3. Any variables encountered are declared to a Z3 instance. More...

Typedefs
using	CompilerResultOrError = std::optional<std::reference_wrapper<const CompilerResult>>
using	ConstraintsVector = std::vector<const IR::Expression *>
using	DCGVertexType = const IR::Node *
using	DCGVertexTypeSet = std::unordered_set<DCGVertexType>
using	NodesCallGraph = ExtendedCallGraph<DCGVertexType>
using	ReachabilityHashType = std::unordered_map<cstring, DCGVertexTypeSet>
using	ReachabilityResult = std::pair<bool, const IR::Expression *>
using	SymbolicMapType = absl::btree_map<IR::StateVariable, const IR::Expression *>
	Symbolic maps map a state variable to a IR::Expression.
using	Z3DeclaredVariablesMap = std::vector<ordered_map<unsigned, const IR::SymbolicVariable *>>

Functions
std::vector< const IR::Type_Declaration * >	argumentsToTypeDeclarations (const IR::IGeneralNamespace *ns, const IR::Vector< IR::Argument > *inputArgs)
std::vector< uint8_t >	convertBigIntToBytes (const big_int &dataInt, int targetWidthBits, bool padLeft)
std::optional< std::string >	convertToIpv4String (const std::vector< uint8_t > &byteArray)
std::optional< std::string >	convertToIpv6String (const std::vector< uint8_t > &byteArray)
std::optional< std::string >	convertToMacString (const std::vector< uint8_t > &byteArray)
void	enableInformationLogging ()
	Enable the printing of basic run information.
void	enablePerformanceLogging ()
	Enable printing of timing reports.
const IR::IDeclaration *	findProgramDecl (const IR::IGeneralNamespace *ns, const IR::Path *path)
	Looks up a declaration from a path. A BUG occurs if no declaration is found.
const IR::IDeclaration *	findProgramDecl (const IR::IGeneralNamespace *ns, const IR::PathExpression *pathExpr)
	Looks up a declaration from a path expression. A BUG occurs if no declaration is found.
std::string	formatBin (const big_int &value, int width, const FormatOptions &formatOptions=FormatOptions())
	Format.
std::string	formatBinExpr (const IR::Expression *expr, const FormatOptions &formatOptions)
std::string	formatBinOrHex (const big_int &value, const FormatOptions &formatOptions=FormatOptions())
	Format.
std::string	formatBinOrHex (const big_int &value, int width, const FormatOptions &formatOptions)
std::string	formatBinOrHexExpr (const IR::Expression *expr, const FormatOptions &formatOptions)
std::string	formatHex (const big_int &value, int width, const FormatOptions &formatOptions=FormatOptions())
	Format.
std::string	formatHexExpr (const IR::Expression *expr, const FormatOptions &formatOptions)
std::string	formatOctal (const big_int &value, const FormatOptions &formatOptions=FormatOptions())
	Format.
std::string	formatOctal (const big_int &value, int width, const FormatOptions &formatOptions)
std::string	formatOctalExpr (const IR::Expression *expr, const FormatOptions &formatOptions)
std::string	insertHexSeparators (const std::string &dataStr)
	Takes a hex-formatted string as input and inserts slashes as separators.
std::string	insertOctalSeparators (const std::string &dataStr)
	Takes an octal-formatted string as input and inserts slashes as separators.
std::string	insertSeparators (const std::string &dataStr, const std::string &separator, size_t stride, bool skipFirst)
std::string	logHelper (boost::format &f)
	Helper function for @printFeature.
template<class T , class... Args>
std::string	logHelper (boost::format &f, T &&t, Args &&...args)
	Helper function for @printFeature.
std::ostream &	operator<< (std::ostream &os, const TraceEvent &event)
template<typename... Arguments>
void	printDebug (const std::string &fmt, Arguments &&...args)
template<typename... Arguments>
void	printFeature (const std::string &label, int level, const std::string &fmt, Arguments &&...args)
template<typename... Arguments>
void	printInfo (const std::string &fmt, Arguments &&...args)
void	printPerformanceReport (const std::optional< std::filesystem::path > &basePath)
const IR::Type_Declaration *	resolveProgramType (const IR::IGeneralNamespace *ns, const IR::Type_Name *type)
	Resolves a Type_Name in the top-level namespace.
const char *	toString (const z3::expr &e)
	Converts a Z3 expression to a string.
const char *	toString (z3::model m)
	Converts a Z3 model to a string.

Detailed Description

Variables internal to P4Tools. These variables do not exist in the P4 program itself, but are generated and added to the environment by the P4Tools tooling. These variables are also used for SMT solvers as symbolic variables.

---

Class Documentation

P4::P4Tools::FormatOptions

struct P4::P4Tools::FormatOptions

Defines common formatting options.

Class Members
bool	padOutput = true	The output will be padded on the left with zeroes to visually represent the full requested width.
bool	usePrefix = true	The string will contain a prefix denoting the numeral system. Hexadecimal strings are prefixed with "0x", whereas binary strings are prefixed with "0b" and octal strings with "0".
bool	useSeparator = false	Insert separators into the produced string. The output is formatted in groups of four digits separated by the underscore character. If not a multiple of four, the first group will have the remainder digits; for example, "0xBAD_BEEF" for hex or "0b10_1010" for binary.
bool	useUpperCaseHex = true	In case of hex strings, use uppercase instead of lowercase letters.

P4::P4Tools::InheritedCompilerOptionSpec

struct P4::P4Tools::InheritedCompilerOptionSpec

Specifies a command-line option to inherit from the compiler, and any special handling for the option.

Class Members
const char *	argName	A descriptive name for the parameter to the option, or nullptr if the option has no parameters.
const char *	description	A description of the option.
optional< function< bool(const char *)> >	handler	An optional handler for the option. If provided, this is executed before the option is forwarded to the compiler. Any argument to the option is provided to the handler. The handler should return true on successful processing, and false otherwise.
const char *	option	The name of the command-line option. For example, "--target".

Typedef Documentation

CompilerResultOrError

using P4::P4Tools::CompilerResultOrError = std::optional<std::reference_wrapper<const CompilerResult>>

P4Tools compilers may return an error instead of a compiler result. This is a convenience definition for the return value.

ConstraintsVector

using P4::P4Tools::ConstraintsVector = std::vector<const IR::Expression *>

A list of constraints. These constraints may take the form of "x == 8w1","x != y", where "x" and "y" are symbolic variables. They are expressed in P4C IR form and may be consumed by SMT or similar solvers.

Z3DeclaredVariablesMap

using P4::P4Tools::Z3DeclaredVariablesMap = std::vector<ordered_map<unsigned, const IR::SymbolicVariable *>>

A stack of maps, which map Z3-internal expression IDs of declared Z3 variables to their corresponding P4 state variable. The maps are pushed and pop according to the solver push() and pop() operations.

Function Documentation

argumentsToTypeDeclarations()

std::vector< const IR::Type_Declaration * > P4::P4Tools::argumentsToTypeDeclarations	(	const IR::IGeneralNamespace *	ns,
		const IR::Vector< IR::Argument > *	inputArgs )

Converts the list of arguments @inputArgs to a list of type declarations. Any names appearing in the arguments are resolved with @ns. This is mainly useful for inspecting package instances.

convertBigIntToBytes()

std::vector< uint8_t > P4::P4Tools::convertBigIntToBytes	(	const big_int &	dataInt,
		int	targetWidthBits,
		bool	padLeft = false )

Converts a big integer input into a vector of bytes with the size targetWidthBits /8. If the integer value is smaller than the request bit size and

Parameters

padLeft

is false, padding is added on the right-hand side of the vector (the "least-significant" side). Otherwise, padding is added on the left-hand side, (the "most-significant side")

Chunk size is 8 bits, i.e., a byte.

convertToIpv4String()

std::optional< std::string > P4::P4Tools::convertToIpv4String

(

const std::vector< uint8_t > &

byteArray

)

Convert a byte array into a IPv4 string of the form "x.x.x.x".

Returns

std::nullopt if the conversion fails.

convertToIpv6String()

std::optional< std::string > P4::P4Tools::convertToIpv6String

(

const std::vector< uint8_t > &

byteArray

)

Convert a byte array into a IPv4 string of the form "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx".

Returns

std::nullopt if the conversion fails.

Chunk size is 8 bits, i.e., a byte.

convertToMacString()

std::optional< std::string > P4::P4Tools::convertToMacString

(

const std::vector< uint8_t > &

byteArray

)

Convert a byte array into a MAC string of the form "xx:xx:xx:xx:xx:xx".

Returns

std::nullopt if the conversion fails.

formatBin()

std::string P4::P4Tools::formatBin	(	const big_int &	value,
		int	width,
		const FormatOptions &	formatOptions = FormatOptions() )

Format.

• value as a binary string.

formatBinExpr()

std::string P4::P4Tools::formatBinExpr	(	const IR::Expression *	expr,
		const FormatOptions &	formatOptions = FormatOptions() )

If the given

• expr is an unsigned bit-typed constant, it is formatted as a binary string. Otherwise, this delegates to P4C's operator<<.

formatBinOrHex()

std::string P4::P4Tools::formatBinOrHex	(	const big_int &	value,
		const FormatOptions &	formatOptions = FormatOptions() )

Format.

• value as either binary or hexadecimal string.

formatBinOrHexExpr()

std::string P4::P4Tools::formatBinOrHexExpr	(	const IR::Expression *	expr,
		const FormatOptions &	formatOptions = FormatOptions() )

If the given

• expr is an unsigned bit-typed constant, it is formatted as a binary or hexadecimal string. Otherwise, this delegates to P4C's operator<<.

formatHex()

std::string P4::P4Tools::formatHex	(	const big_int &	value,
		int	width,
		const FormatOptions &	formatOptions = FormatOptions() )

Format.

• value as a hexadecimal string.

formatHexExpr()

std::string P4::P4Tools::formatHexExpr	(	const IR::Expression *	expr,
		const FormatOptions &	formatOptions = FormatOptions() )

If the given

• expr is an unsigned bit-typed constant, it is formatted as a hexadecimal string. Otherwise, this delegates to P4C's operator<<.

formatOctal()

std::string P4::P4Tools::formatOctal	(	const big_int &	value,
		const FormatOptions &	formatOptions = FormatOptions() )

Format.

• value as a octal string.

formatOctalExpr()

std::string P4::P4Tools::formatOctalExpr	(	const IR::Expression *	expr,
		const FormatOptions &	formatOptions = FormatOptions() )

If the given

• expr is an unsigned bit-typed constant, it is formatted as an octal string. Otherwise, this delegates to P4C's operator<<.

insertSeparators()

std::string P4::P4Tools::insertSeparators	(	const std::string &	dataStr,
		const std::string &	separator = "\\x",
		size_t	stride = 2,
		bool	skipFirst = false )

Insert separators into

Parameters

dataStr	every
stride.	If
skipFirst	is true, this will not add a separator to the beginning of the string. This function always pads to the width of
stride.

printDebug()

template<typename... Arguments>

void P4::P4Tools::printDebug	(	const std::string &	fmt,
		Arguments &&...	args )

Convenience function for printing debug information. Easier to use then LOG(XX) since we only need one specific log-level across all files. Can be invoked with "-T tools_debug:4".

printFeature()

template<typename... Arguments>

void P4::P4Tools::printFeature	(	const std::string &	label,
		int	level,
		const std::string &	fmt,
		Arguments &&...	args )

A helper function that allows us to configure logging for a particular feature. This code is taken from

printInfo()

template<typename... Arguments>

void P4::P4Tools::printInfo	(	const std::string &	fmt,
		Arguments &&...	args )

Helper functions that prints strings associated with basic tool information. For example, the seed, status of test case generation, etc.

printPerformanceReport()

void P4::P4Tools::printPerformanceReport

(

const std::optional< std::filesystem::path > &

basePath = std::nullopt

)

Print a performance report if performance logging is enabled. If a file is provided, it will be written to the file.