As of gtkwave-1.3.79, the viewer now supports signal aliasing through both
plaintext filters and through external program filters.  Note that signal
aliasing is a strict one-to-one correspondence so the value represented in
the viewer must exactly represent what format your filter expects.  
(e.g., binary, hexadecimal, with leading base markers, etc.)  For your
convenience, the comparisons are case insensitive however.


Text Filters
============

The viewer looks at a file of the following format:

#
# this is a comment
#
00 Idle
01 Advance
10 Stop
11 Reset

...the first non-whitespace item is treated as a literal value that would
normally be printed by the viewer and the remaining items on the line are
substitution text.  Any time this text is encountered if the filter is
active, it will replace the left-hand side text with the right-hand side.  
Leading and trailing whitespaces are removed from the right-hand side
item.

To turn on the filter:

1) Highlight the signals you want filtered
2) Edit->Data Format->Translate Filter File->Enable and Select
3) Add Filter to List
4) Click on filter filename
5) Select filter filename from list
6) OK

To turn off the filter:

1) Highlight the signals you want unfiltered.
2) Edit->Data Format->Translate Filter File->Disable

(*) Filters configurations load and save properly to and from save files.


Process Filters
===============

An external process that accepts one line in from stdin and returns with 
data on stdout can be used as a process filter.  An example of this are 
disassemblers.  The following sample code would show how to interface with 
a disassembler function in C:

	int main(int argc, char **argv)
	{
	while(1)
	        {
	        char buf[1025], buf2[1025];
	
	        buf[0] = 0;
	        fscanf(stdin, "%s", buf);
	        if(buf[0]) 
	                {
	                int hx;
	                sscanf(buf, "%x", &hx);
	                ppc_dasm_one(buf2, 0, hx);
	                printf("%s\n", buf2);
	                fflush(stdout);
	                }
	        }

	return(0);
	}

...note that the fflush(stdout) is necessary, otherwise gtkwave will hang.  
Also note that every line of input needs to generate a line of output or 
the viewer will hang too.

To turn on the filter:

1) Highlight the signals you want filtered
2) Edit->Data Format->Translate Filter Process->Enable and Select
3) Add Proc Filter to List
4) Click on filter filename
5) Select filter filename from list
6) OK


To turn off the filter:

1) Highlight the signals you want unfiltered.
2) Edit->Data Format->Translate Filter Process->Disable

(*) Filters configurations load and save properly to and from save files.


Caveats
=======

Filters are a new, experimental feature as of 1.3.79.  It is highly
possible that some OSs (e.g., AIX) could exhibit some problems due to how
X11 file descriptors are handled after a fork.  This appears to work OK
under linux, for AIX a special chopped down handler needed to be used.  
In the future, the AIX version will also need additional signal handling
to ensure that the filter processes are always killed when gtkwave
terminates.  Linux uses a double fork() with a speciall getppid()  
handler to ensure this always occurs.

18nov05ajb
