wireshark/epan/dfilter

$Id$

How does the display filter logic work?
=======================================

scanner.l looks at the display filter string and finds reserved words,
punctuation, etc. This information gets passed to the parser produced by
grammar.lemon. The grammar's job is to create a syntax-tree out of the
information provided by the scanner. The syntax tree organizes the
information from the scanner into something that is grammatical in the
dfilter language.

The routines in semcheck.c then check the semantics of the syntax tree, and do
any modifications necessary to the syntax tree to make the dfilter work....
things like converting val_strings to integers, etc.

Then gencode.c converts the syntax tree into a list of "dfvm" (display filter
virtual machine) instructions. These dfvm instructions are what runs the
display filter engine.

Example: add an 'in' display filter operation
=============================================

This example has been discussed on wireshark-dev in April 2004. It illustrates
how a more complex operation can be added to the display filter language.

Question:

	If I want to add an 'in' display filter operation, I need to define
	several things. This can happen in different ways. For instance,
	every value from the "in" value collection will result in a test.
	There are 2 options here, either a test for a single value:

		(x in {a b c})

	or a test for a value in a given range:

		(x in {a ... z})

	or even a combination of both. The former example can be reduced to:

		((x == a) or (x == b) or (x == c))

	while the latter can be reduced to

		((x >= MIN(a, z)) and (x <= MAX(a, z)))

	I understand that I can replace "x in {" with the following steps:
	first store x in the "in" test buffer, then add "(" to the display
	filter expression internally.

	Similarly I can replace the closing brace "}" with the following steps:
	release x from the "in" test buffer and then add ")" to the display
	filter expression internally.

	How could I do this?

Answer:

	This could be done in grammar.lemon. The grammar would produce syntax
	tree nodes, combining them with "or", when it is given tokens that
	represent the "in" syntax.

	It could also be done later in the process, maybe in semcheck.c. But
	if you can do it earlier, in grammar.lemon, then you shouldn't have to
	worry about modifying anything in semcheck.c, as the syntax tree that
	is passed to semcheck.c won't contain any new type of operators... just
	lots of nodes combined with "or".

How to add an operator FOO to the display filter language?
==========================================================

Go to wireshark/epan/dfilter/

Edit grammar.lemon and add the operator. Add the operator FOO and the test logic (defining TEST_OP_FOO).

Edit scanner.l and add the operator name(s) hence defining TOKEN_TEST_FOO. Also update the simple() or add the new operand's code.

Edit sttype-test.h and add the TEST_OP_FOO to the list of test operations.

Edit sttype-test.c and add TEST_OP_FOO to the num_operands() method.

Edit gencode.c, add TEST_OP_FOO in the gen_test() method by defining ANY_FOO.

Edit dfvm.h and add ANY_FOO to the enum dfvm_opcode_t structure.

Edit dfvm.c and add ANY_FOO to dfvm_dump() (for the dftest display filter test binary), to dfvm_apply() hence defining the methods fvalue_foo().

Edit semcheck.c and look at the check_relation_XXX() methods if they still apply to the foo operator; if not, amend the code. Start from the check_test() method to discover the logic.

Go to wireshark/epan/ftypes/

Edit ftypes.h and declare the fvalue_foo(), ftype_can_foo() and fvalue_foo() methods. Add the cmp_foo() method to the struct _ftype_t.

This is the first time that a make in wireshark/epan/dfilter/ can succeed. If it fails, then some code in the previously edited files must be corrected.

Edit ftypes.c and define the fvalue_foo() method with its associated logic. Define also the ftype_can_foo() and fvalue_foo() methods.

Edit all ftype-*.c files and add the required fvalue_foo() methods.

This is the point where you should be able to compile without errors in wireshark/epan/ftypes/. If not, first fix the errors.

Go to wireshark/epan/ and run make. If this one succeeds, then we're almost done as no errors should occur here.

Go to wireshark/ and run make. One thing to do is make dftest and see if you can construct valid display filters with your new operator. Or you may want to move directly to the generation of wireshark.

Look also at wireshark/gtk/dfilter_expr_dlg.c and edit the display filter expression generator.