dfvm.h File Reference

#include <wsutil/regex.h>
#include "dfilter-int.h"
#include "syntax-tree.h"
#include "drange.h"
#include "dfunctions.h"

Go to the source code of this file.

Classes
struct	dfvm_value_t
	Represents a typed value used in display filter virtual machine (DFVM) operations. More...
struct	dfvm_insn_t
	Represents a single instruction in the display filter virtual machine (DFVM). More...

Macros
#define	ASSERT_DFVM_OP_NOT_REACHED(op)    ws_error("Invalid dfvm opcode '%s'.", dfvm_opcode_tostr(op))
	Aborts with a fatal error when an unhandled DFVM opcode is encountered.
#define	dfvm_value_get_fvalue(val)   ((val)->value.fvalue_p->pdata[0])
	Extracts the first fvalue pointer from a DFVM register value's fvalue list.

Enumerations
enum	dfvm_value_type_t {   EMPTY , FVALUE , HFINFO , RAW_HFINFO ,   HFINFO_VS , INSN_NUMBER , REGISTER , INTEGER ,   DRANGE , FUNCTION_DEF , PCRE }
	Discriminator tag identifying the active payload in a dfvm_value_t union. More...
enum	dfvm_opcode_t {   DFVM_NULL , DFVM_IF_TRUE_GOTO , DFVM_IF_FALSE_GOTO , DFVM_CHECK_EXISTS ,   DFVM_CHECK_EXISTS_R , DFVM_NOT , DFVM_RETURN , DFVM_READ_TREE ,   DFVM_READ_TREE_R , DFVM_READ_REFERENCE , DFVM_READ_REFERENCE_R , DFVM_PUT_FVALUE ,   DFVM_ALL_EQ , DFVM_ANY_EQ , DFVM_ALL_NE , DFVM_ANY_NE ,   DFVM_ALL_GT , DFVM_ANY_GT , DFVM_ALL_GE , DFVM_ANY_GE ,   DFVM_ALL_LT , DFVM_ANY_LT , DFVM_ALL_LE , DFVM_ANY_LE ,   DFVM_ALL_CONTAINS , DFVM_ANY_CONTAINS , DFVM_ALL_MATCHES , DFVM_ANY_MATCHES ,   DFVM_SET_ALL_IN , DFVM_SET_ANY_IN , DFVM_SET_ALL_NOT_IN , DFVM_SET_ANY_NOT_IN ,   DFVM_SET_ADD , DFVM_SET_ADD_RANGE , DFVM_SET_CLEAR , DFVM_SLICE ,   DFVM_LENGTH , DFVM_BITWISE_AND , DFVM_UNARY_MINUS , DFVM_ADD ,   DFVM_SUBTRACT , DFVM_MULTIPLY , DFVM_DIVIDE , DFVM_MODULO ,   DFVM_CALL_FUNCTION , DFVM_STACK_PUSH , DFVM_STACK_POP , DFVM_NOT_ALL_ZERO ,   DFVM_NO_OP }
	Opcodes for the Display Filter Virtual Machine (DFVM) instruction set. More...

Functions
const char *	dfvm_opcode_tostr (dfvm_opcode_t code)
	Converts a DFVM opcode to its string representation.
dfvm_insn_t *	dfvm_insn_new (dfvm_opcode_t op)
	Creates a new DFVM instruction with the specified opcode.
void	dfvm_insn_replace_no_op (dfvm_insn_t *insn)
	Replaces an instruction with a no-op.
void	dfvm_insn_free (dfvm_insn_t *insn)
	Free a DFVM instruction.
dfvm_value_t *	dfvm_value_new (dfvm_value_type_t type)
	Create a new DFVM value.
dfvm_value_t *	dfvm_value_ref (dfvm_value_t *v)
	Increment the reference count of a dfvm_value_t.
void	dfvm_value_unref (dfvm_value_t *v)
	Decrements the reference count of a dfvm_value_t object and frees it if the reference count reaches zero.
dfvm_value_t *	dfvm_value_new_fvalue (fvalue_t *fv)
	Creates a new DFVM value of type FVALUE.
dfvm_value_t *	dfvm_value_new_hfinfo (header_field_info *hfinfo, bool raw, bool val_str)
	Create a new dfvm_value_t with header field information.
dfvm_value_t *	dfvm_value_new_register (int reg)
	Creates a new dfvm_value_t representing a register.
dfvm_value_t *	dfvm_value_new_drange (drange_t *dr)
	Creates a new dfvm_value_t with type DRANGE.
dfvm_value_t *	dfvm_value_new_funcdef (df_func_def_t *funcdef)
	Create a new DFVM value of type FUNCTION_DEF.
dfvm_value_t *	dfvm_value_new_pcre (ws_regex_t *re)
	Creates a new PCRE value.
dfvm_value_t *	dfvm_value_new_uint (unsigned num)
	Create a new DFVM value with an unsigned integer.
void	dfvm_dump (FILE *f, dfilter_t *df, uint16_t flags)
	Dumps the bytecode of a dfilter_t to a file.
char *	dfvm_dump_str (wmem_allocator_t *alloc, dfilter_t *df, uint16_t flags)
	Dumps a string representation of a dfilter.
bool	dfvm_apply (dfilter_t *df, proto_tree *tree)
	Applies a display filter to a protocol tree.
bool	dfvm_apply_full (dfilter_t *df, proto_tree *tree, GPtrArray **fvals)
	Apply a full Dissector Filter VM (DFVM) to a protocol tree.
fvalue_t *	dfvm_get_raw_fvalue (const field_info *fi)
	Retrieves the raw value of a field as a GByteArray.

Detailed Description

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 2001 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

ASSERT_DFVM_OP_NOT_REACHED

#define ASSERT_DFVM_OP_NOT_REACHED

(

op

)

ws_error("Invalid dfvm opcode '%s'.", dfvm_opcode_tostr(op))

Aborts with a fatal error when an unhandled DFVM opcode is encountered.

Parameters

op	The invalid dfvm_opcode_t value that was reached.

dfvm_value_get_fvalue

#define dfvm_value_get_fvalue

(

val

)

((val)->value.fvalue_p->pdata[0])

Extracts the first fvalue pointer from a DFVM register value's fvalue list.

Parameters

val	Pointer to a dfvm_value_t with type FVALUE.

Returns

The first fvalue_t pointer stored in the value's pdata array.

Enumeration Type Documentation

dfvm_opcode_t

enum dfvm_opcode_t

Opcodes for the Display Filter Virtual Machine (DFVM) instruction set.

Enumerator
DFVM_NULL	Null/invalid opcode; should never be executed
DFVM_IF_TRUE_GOTO	Branch to target instruction if the top of stack is true
DFVM_IF_FALSE_GOTO	Branch to target instruction if the top of stack is false
DFVM_CHECK_EXISTS	Push true if a given field exists in the packet tree
DFVM_CHECK_EXISTS_R	Push true if a given field exists, using a raw field reference
DFVM_NOT	Logically negate the boolean at the top of the stack
DFVM_RETURN	Halt execution and return the top-of-stack value as the filter result
DFVM_READ_TREE	Read all values of a field from the protocol tree into a register
DFVM_READ_TREE_R	Read all raw values of a field from the protocol tree into a register
DFVM_READ_REFERENCE	Read a named field reference value into a register
DFVM_READ_REFERENCE_R	Read a named raw field reference value into a register
DFVM_PUT_FVALUE	Load a constant fvalue literal into a register
DFVM_ALL_EQ	True if all values in register A equal any value in register B
DFVM_ANY_EQ	True if any value in register A equals any value in register B
DFVM_ALL_NE	True if all values in register A are not equal to all values in register B
DFVM_ANY_NE	True if any value in register A is not equal to any value in register B
DFVM_ALL_GT	True if all values in register A are greater than any value in register B
DFVM_ANY_GT	True if any value in register A is greater than any value in register B
DFVM_ALL_GE	True if all values in register A are greater than or equal to any value in register B
DFVM_ANY_GE	True if any value in register A is greater than or equal to any value in register B
DFVM_ALL_LT	True if all values in register A are less than any value in register B
DFVM_ANY_LT	True if any value in register A is less than any value in register B
DFVM_ALL_LE	True if all values in register A are less than or equal to any value in register B
DFVM_ANY_LE	True if any value in register A is less than or equal to any value in register B
DFVM_ALL_CONTAINS	True if all values in register A contain the value in register B
DFVM_ANY_CONTAINS	True if any value in register A contains the value in register B
DFVM_ALL_MATCHES	True if all values in register A match the PCRE in register B
DFVM_ANY_MATCHES	True if any value in register A matches the PCRE in register B
DFVM_SET_ALL_IN	True if all values in a register are members of the set
DFVM_SET_ANY_IN	True if any value in a register is a member of the set
DFVM_SET_ALL_NOT_IN	True if all values in a register are not members of the set
DFVM_SET_ANY_NOT_IN	True if any value in a register is not a member of the set
DFVM_SET_ADD	Add a single value to the current set under construction
DFVM_SET_ADD_RANGE	Add a value range (inclusive) to the current set under construction
DFVM_SET_CLEAR	Discard the current set and free its resources
DFVM_SLICE	Extract a byte-range slice from the values in a register
DFVM_LENGTH	Compute the length of field values and store as integer fvalues
DFVM_BITWISE_AND	Perform bitwise AND between values in two registers
DFVM_UNARY_MINUS	Negate (unary minus) each value in a register
DFVM_ADD	Add corresponding values from two registers
DFVM_SUBTRACT	Subtract corresponding values from two registers
DFVM_MULTIPLY	Multiply corresponding values from two registers
DFVM_DIVIDE	Divide corresponding values from two registers
DFVM_MODULO	Compute modulo of corresponding values from two registers
DFVM_CALL_FUNCTION	Invoke a display filter function with arguments from the stack
DFVM_STACK_PUSH	Push a register's value list onto the function argument stack
DFVM_STACK_POP	Pop N entries from the function argument stack
DFVM_NOT_ALL_ZERO	True if not all bytes in the register's values are zero
DFVM_NO_OP	No operation; placeholder or padding instruction

dfvm_value_type_t

enum dfvm_value_type_t

Discriminator tag identifying the active payload in a dfvm_value_t union.

Enumerator
EMPTY	No value is set; slot is unused
FVALUE	Payload is a field value (fvalue_t)
HFINFO	Payload is a pointer to a header field descriptor (header_field_info)
RAW_HFINFO	Payload is a pointer to a raw (undecoded) header field descriptor
HFINFO_VS	Payload is a header field descriptor with an associated value string
INSN_NUMBER	Payload is a DFVM instruction index (branch target)
REGISTER	Payload is a DFVM virtual register number
INTEGER	Payload is a bare integer constant
DRANGE	Payload is a display filter range (drange_t)
FUNCTION_DEF	Payload is a display filter function definition (df_func_def_t)
PCRE	Payload is a compiled Perl-Compatible Regular Expression (pcre2)

Function Documentation

dfvm_apply()

bool dfvm_apply	(	dfilter_t *	df,
		proto_tree *	tree
	)

Applies a display filter to a protocol tree.

Parameters

df	The display filter to apply.
tree	The protocol tree to which the filter will be applied.

Returns

true if the filter was successfully applied, false otherwise.

dfvm_apply_full()

bool dfvm_apply_full	(	dfilter_t *	df,
		proto_tree *	tree,
		GPtrArray **	fvals
	)

Apply a full Dissector Filter VM (DFVM) to a protocol tree.

This function executes all instructions in the DFVM on the given protocol tree, updating the filter values accordingly.

Parameters

df	The Dissector Filter VM to apply.
tree	The protocol tree to process.
fvals	Pointer to an array of filter values, or NULL if not needed.

dfvm_dump()

void dfvm_dump	(	FILE *	f,
		dfilter_t *	df,
		uint16_t	flags
	)

Dumps the bytecode of a dfilter_t to a file.

Parameters

f	The file pointer where the bytecode will be written.
df	The dfilter_t whose bytecode is to be dumped.
flags	Flags that control the dumping process.

dfvm_dump_str()

char * dfvm_dump_str	(	wmem_allocator_t *	alloc,
		dfilter_t *	df,
		uint16_t	flags
	)

Dumps a string representation of a dfilter.

Parameters

alloc	Memory allocator for the buffer.
df	The dfilter to dump.
flags	Flags controlling what information is included in the dump.

Returns

A wmem_strbuf_t containing the dumped string.

dfvm_get_raw_fvalue()

fvalue_t * dfvm_get_raw_fvalue

(

const field_info *

fi

)

Retrieves the raw value of a field as a GByteArray.

Parameters

fi	Pointer to the field_info structure containing the field information.

Returns

A GByteArray containing the raw value of the field, or NULL if an error occurs.

dfvm_insn_free()

void dfvm_insn_free

(

dfvm_insn_t *

insn

)

Free a DFVM instruction.

This function frees a DFVM instruction and unrefs any arguments it may have.

Parameters

insn	The DFVM instruction to free.

dfvm_insn_new()

dfvm_insn_t * dfvm_insn_new

(

dfvm_opcode_t

op

)

Creates a new DFVM instruction with the specified opcode.

Parameters

op	The operation code for the new instruction.

Returns

A pointer to the newly created dfvm_insn_t structure.

dfvm_insn_replace_no_op()

void dfvm_insn_replace_no_op

(

dfvm_insn_t *

insn

)

Replaces an instruction with a no-op.

This function replaces the given instruction with a no-op (no operation) instruction. It unrefs any arguments associated with the original instruction before setting it to no-op.

Parameters

insn	Pointer to the instruction to be replaced.

dfvm_opcode_tostr()

const char * dfvm_opcode_tostr

(

dfvm_opcode_t

code

)

Converts a DFVM opcode to its string representation.

Parameters

code	The DFVM opcode to convert.

Returns

const char* A string representing the opcode.

dfvm_value_new()

dfvm_value_t * dfvm_value_new

(

dfvm_value_type_t

type

)

Create a new DFVM value.

Parameters

type	The type of the value to create.

Returns

A pointer to the newly created dfvm_value_t.

dfvm_value_new_drange()

dfvm_value_t * dfvm_value_new_drange

(

drange_t *

dr

)

Creates a new dfvm_value_t with type DRANGE.

Parameters

dr	Pointer to the drange_t structure.

Returns

A pointer to the newly created dfvm_value_t.

dfvm_value_new_funcdef()

dfvm_value_t * dfvm_value_new_funcdef

(

df_func_def_t *

funcdef

)

Create a new DFVM value of type FUNCTION_DEF.

Parameters

funcdef

Pointer to the function definition.

Returns

dfvm_value_t* Pointer to the newly created DFVM value.

dfvm_value_new_fvalue()

dfvm_value_t * dfvm_value_new_fvalue

(

fvalue_t *

fv

)

Creates a new DFVM value of type FVALUE.

Parameters

fv	Pointer to the fvalue_t structure.

Returns

dfvm_value_t* Pointer to the newly created DFVM value.

dfvm_value_new_hfinfo()

dfvm_value_t * dfvm_value_new_hfinfo	(	header_field_info *	hfinfo,
		bool	raw,
		bool	val_str
	)

Create a new dfvm_value_t with header field information.

Parameters

hfinfo	Pointer to the header field information.
raw	Flag indicating if the value is in raw format.
val_str	Flag indicating if the value is a string.

Returns

dfvm_value_t* Pointer to the newly created dfvm_value_t.

dfvm_value_new_pcre()

dfvm_value_t * dfvm_value_new_pcre

(

ws_regex_t *

re

)

Creates a new PCRE value.

Parameters

re	The PCRE regular expression to be stored in the value.

Returns

A pointer to the newly created PCRE value.

dfvm_value_new_register()

dfvm_value_t * dfvm_value_new_register

(

int

reg

)

Creates a new dfvm_value_t representing a register.

Parameters

reg	The register value to be stored in the dfvm_value_t.

Returns

A pointer to the newly created dfvm_value_t.

dfvm_value_new_uint()

dfvm_value_t * dfvm_value_new_uint

(

unsigned

num

)

Create a new DFVM value with an unsigned integer.

Parameters

num	The unsigned integer value to store in the new DFVM value.

Returns

dfvm_value_t* A pointer to the newly created DFVM value.

dfvm_value_ref()

dfvm_value_t * dfvm_value_ref

(

dfvm_value_t *

v

)

Increment the reference count of a dfvm_value_t.

Parameters

v	Pointer to the dfvm_value_t whose reference count is to be incremented.

Returns

The same pointer to the dfvm_value_t.

dfvm_value_unref()

void dfvm_value_unref

(

dfvm_value_t *

v

)

Decrements the reference count of a dfvm_value_t object and frees it if the reference count reaches zero.

Parameters

v	Pointer to the dfvm_value_t object to be unreferenced.