########################################################
##  GAL/PAL chip emulator  --  SELFTESTS              ##
##  Copyright (C) 2008 Michael Buesch <mb@bu3sch.de>  ##
##  Licensed under the GNU/GPL version 2 or later     ##
########################################################


Generating new testcases
========================

You can generate testcases from a .PDS files' SIMULATION segment with
the "testgenerator.py" script. The script takes the .PDS file on stdin
and writes the .SIM file to stdout.
Note that the generator does not support all .PDS keywords, yet.


.SIM file syntax
================

The .SIM file is a trivial script for executing emulator tests.
One test looks like this:
NAME {
	# Test actions go here
}

NAME is a random name string used for error logging, only.
All lines starting with a #-char are treated as a comment.
Comments and whitespace are ignored by the interpreter.

The emulator state is reset before the first test is executed. After this,
the tests are executed from top to bottom. So the emulator keeps state
across tests!
There are a few keywords available to execute actions inside of the tests.


KEYWORDS
========

Keywords are described here in the precedence order they are executed!
(so INPUT has precedence over OUTPUT, for example)

EXPECTFAIL "exception message string"
	The test this keyword appears in is expected to fail with
	the specified exception message string. The string must
	match exactly. The test will successfully terminate, if the
	emulator exits with this error, only.

INPUT a=1 b=1 c=0
	Set the input pin states of a, b and c.
	a, b and c must be numeric pin names.
	There can be a variable number of pin state assignments per
	INPUT action.

OUTPUT a=1 b=0 c=1
	Check the output pin states of a, b and c against the values.
	There can be a variable number of pin state checks per
	OUTPUT action.
	An error exception will be raised, if one output does not match
	the expected state.