dmfind - Drive mode transition algorithm finder
===============================================

Copyright 2006 Werner Almesberger

The files in this package are distributed under the terms of the
GNU General Public License (GPL), version 2. This license can be
obtained from  http://www.gnu.org/licenses/gpl.txt


Introduction
------------

Changing drive modes on PSoC devices can be tricky. Just writing
the new values to PRTxDMx and PRTxDR may cause undesirable
transitions, like 0->1->Z (this may cause a conflict if the pin
is operating as a "wired or"), or 0->Z->0R (this may cause a
conflict if there is a high-impedance pull-up on the line, and
the line drives an edge-triggered input).

The tools in this package help to test certain properties of drive
mode change algorithm, and to automatically find optimal algorithms
with given properties.


Definitions
-----------

We define two properties of the changes effected by an algorithm:

- we call it "monotonous" if the sequence of changes is either a
  subset of 0->0R->Z->1R->1 or a subset of the reversed sequence,
  1->1R->Z->0R->0.

- we call it "non-extremal" if the sequence will never include a
  strong drive, i.e., "0" or "1", unless either the initial state
  or the final state is that same strong drive.


dmmon
-----

dmmon.c tests that a drive mode change algorithm is monotonous.
To use it, put your algorithm in the function "doit", adjust the
counters in "main", and run it. If it finds a problem, it prints
a history of changes, and stops.

The counter values are four bits, 0b<DM2><DM1><DM0><DR>. For
example,

    for (a = 0; a < 16; a += 2)
	for (b = 1; b < 16; b += 2)

would try all transitions with DR=0 to DR=1.


finddm
------

finddm.c finds an algorithm with optimal run-time with a given
set of properties. It does this by doing a brute-force search
over the roughly 8! possible sequences of changing the DR and DMx
bits, testing each against the desired properties.

finddm calculates the run time of each algorithm, assuming that
we start with XIO=0 and that all operations are AND reg[expr],expr,
OR reg[expr],expr, or MOV reg[expr],expr . If more than one
algorithm with optimal run-time exists, finddm will report the
first it stumbles upon.

In order to make the wait more entertaining, finddm prints each
algorithm that is better than the previous ones.

The properties of the algorithm are determined by the following
definitions:

  -DFILTER=...
    specifies which set of transitions should be considered.
    The following filters are pre-defined:

    FILTER_ANY	  transitions between all DMx and DR values
    FILTER_DR0    transitions where DR remains 0
    FILTER_DR1    transitions where DR remains 1
    FILTER_DR0_1  transitions where DR changes from 0 to 1
    FILTER_DR1_0  transitions where DR changes from 1 to 0
    FILTER_DRx    transitions where DR changes (either way)

  -DCOND=...
    specifies the condition to test. The following conditions
    are pre-defined:

    monotonous   the sequence of changes is monotonous, as
		 defined above
    nonextremal  the seqence of changes is non-extremal

The script "run" executes "finddm" for various settings. "make run"
runs "run", and records the results in the file "log".
