Glossary
Michael Elizabeth Chastain
<mec@duracef.shout.net>
Sat 18 Nov 1995

Copyright 1995 Michael Chastain
Licensed under the Gnu Public License, Version 2



Arg

    An argument to a system call.  An arg is not a register value: some
    system calls do not take their args in registers!  Arg handling
    takes care of pesky hidden argument blocks such as those for 'mmap',
    'select', IPC calls, and socket calls.



Area

    An address range in the target process.  An area has a type,
    although most of them are 'tyAreaData'.



Ccs

    'const char *', a pointer to a C-style string.



Check

    Like 'machine check', failing a check will cause a fatal error.



Compare

    A particular form of 'check': to compare values from tracing against
    fetched values at replay time.  For instance, the replayer compares
    input arguments on EvSci and the stack pointer and registers on
    EvExec.



Context

    A collection of information used to guide a fetch or store.  The
    store context also contains a lot of per-process information not
    used in storing (the 'big-struct' design method).



Dataset

    A file in the target environment.  Two system calls, 'execve' and
    'uselib', not only take datasets for arguments, but alter the memory
    map of the target in an unstoreable way.  Tracing such a call
    requires reading the dataset, and replaying the call requires
    writing the dataset into a temporary file.  Note that 'open',
    'stat', and other calls which operate on datasets do -not- require
    the dataset to be traced, because the effects of these calls can be
    stored onto the process as usual.



Er

    Error functions.



Event

    Each time the traced process stops, the tracer fetches one event.
    On replay, the replay process stops at the same places, and the
    replayer stores one event.

    Event types are:

	EvBlank		uninitialized 
	EvFirst		an artificially-induced first event
	EvSci		system call, into kernel
	EvSco		system call, out from kernel
	EvExec		execve(2), when successful, induces this event
	EvSignal	a signal
	EvExit		exit
	EvStep		single-step trap
	EvBpt		breakpoint trap

    The basic operations on an event are: fetch, store, and format.

    For their major data, events have a time stamp, an indication
    whether the event is replayable, a list of areas, a list of segs,
    and a list of datasets.



Fetch

    To gather information from a traced process.  Fetching is a const
    operation on the traced process.



Filter

    To take an event from a controlled process and make it work
    properly.  The largest, most important filter is for 'ptrace'.

    There are two phases of filters, 'aw' (after wait) and 'bc' (before
    continuation).



Flat

    A flat is a list of characters used to implement persistence.  The
    flat classes provid 'get' and 'put' methods for simple data types.
    Classes with persistence have 'fromFlat' and 'toFlat' methods.



Fmt

    Abbreviation for 'format'.  To translate data into a human-readable
    string.  Some resource-handler classes report errors as formatted
    strings.



Hungarian

    I use many Hungarian prefixes:

	a		array (C-like)
	addr		address, a target machine address
	ap		auto-pointer
	b		byte, a target machine byte
	bpt		breakpoint
	c		character
	cx		context
	ds		dataset
	ev		event
	f		flag (boolean)
	i		index
	l		list (WhList) or lap (WhLap)
	n		number, a count
	p		pointer
	proc		process
	s		size
	sci		system call in  (into kernel)
	sco		system call out (out of kernel)
	scr		system call return value
	st		state
	ty		type, an enumeration
	w		word, a target machine word

    I also use suffixes to indicate machine-dependent things:

	Lix		Linux 1.3.X	i386
	Sun		SunOS 4.1.X	Sparc



Image

    An mmap'ed image of a file.  This is faster than reading into
    memory, because often the file is a dataset which the target has
    just mmap'ed also.



Insn

    A target machine instruction.  I first saw this term in the Gnu cc
    source.



Line

    An item of machine-dependent configuration information, indexed by
    something.  A line is a read-only struct with a bunch of attributes.

	MsLine		Memory Segment line
	RiLine		Request Ioctl line
	ScLine		System Call line



Linear Pointer

    A 'linear value' is a value constrained such that, at any time,
    exactly one variable holds the address of that value.  A linear
    pointer is a pointer to a linear value.

    I was inspired by Henry Baker's paper: _'Use-Once' Variables and
    Linear Objects_, available at:
    
	ftp://ftp.netcom.com/pub/hb/hbaker/Use1Var.html

    My usage is more like the 'auto pointer' class in the C++ DWP; any
    variation between Henry Baker's ideas and mine is my responsibility.
    Here is my typical case of 'pass by linear reference':

	p1 = new Foo;
	appFoo( p1 );
	...
	appFoo( Foo * & p )
	{
	    lapFoo.appendAp( p );
	    p = 0;
	}



Lap

    A list of auto pointers.  A lap owns the objects to which it points.
    It is used very much like a list.



List

    A dynamic array of values.  In my lists, 'operator []' is always
    const.  There are 'clear' and 'append' methods.  There is an
    'addrNonConst' for rare escapes.



Log

    The list of all events that happened to the process.  The log
    includes enough information to replay the entire execution of the
    process, on the same or different machine.



Map

    A list of all areas in the target process.  A map is used to help
    find which area changed during 'brk' and to fetch *all* the areas
    during signal handling.  To construct the map, it's necessary to
    parse executable and library files as the target calls 'execve' and
    'uselib' on them, as well as to interpret some other calls, such as
    'brk', 'mmap', 'munmap'.



Mec

    My initials: 'Michael Elizabeth Chastain'.



Mm

    Memory types and classes.  These are all in the context of the
    target process.  E.g., an 'MmAddr' is always in the address space of
    the target.



Mode

    A parameter to a call such as 'fcntl', 'ptrace', or 'sysfs' which
    determines the types of the other parameters.  'Unknown mode' is one
    of the ways an event can become unreplayable.



Nasty Name Overlap

    A particular error where the name to 'execve' overlaps with part of
    the 'argv' or 'env' pointer arrays.  Not with one of the strings
    such as 'argv[0]', which is OK; but with the -array of pointers-
    that points to these strings!

    Because of name smashing in the stash, I can't replay a Nasty Name
    Overlap.  If you have an NNO: your program is really sick.  Go debug
    your pointers.



Pr

    Target process classes.  These are mostly non-copyable external
    resource handlers.



Reg

    A target register.



Replay process

    The new process whose executions replays that of the original target
    process.  Stores happen to the replay process.



Scr

    System call return value.  This type has a generic interface with
    OS-specific implementations.  The control process must synthesize
    scr's occasionally to hand back to the viewer process.



Seg

    A segment of target memory.  A seg may have an area, and it may have
    data which are bound to that area.  A seg also has a type, which is
    used for determining its size and for formatting it.



Smash

    When the replay process stops at entry to a system call, the
    replayer smashes some registers in order to force the call to return
    without doing anything (e.g., set the first parameter to '-1' for
    file-handle-oriented calls).

    I would like to simply annul the call, but there is no Linux
    facility for that.  In particular, I can't store into 'ORIG_EAX'.
    So for each call, I have to go look for some illegal parameter value
    that causes it to return without disturbing things or causing wild
    effects when replaying.

    The calls 'brk', 'execve', 'exit', 'mmap', 'munmap', and 'uselib'
    change the address space of the child, which the parent cannot do.
    These calls are not smashed, but are replayed with the same
    arguments.  For 'execve' and 'uselib', this involves arranging for a
    file with the same contents to be available during replay.

    Some calls, such as 'fork' and 'pause', take no arguments, and thus
    are very resistant to smashing.



Stash

    A temporary directory where datasets are stored so that they are
    accessible to the replay process.



Store

    To write onto the registers and memory of a replay process so that
    it looks like the original traced process.



Target

    Usually the trace process, but sometimes any child process.



Ti

    Template instantiation file.  I use manual template instantiation
    because it's fast, simple, portable, and standard.



Trace process

    The original child process which is being traced.  Fetches happen on
    the trace process.



Viewer process

    A process such as 'gdb' or 'strace' which uses ptrace(2) to view a
    child process.



Wh
Wheel

    I don't trust C++ external library facilities, so I wrote some of my
    own simple classes: files, flats, lists and strings.  The 'wheel'
    here refers to what I re-invented.
