Generic support for Boundary Scan Definitions
=============================================

This style of bus access can often be used to control a PCB without knowing
very much about the main chips on it.  Using the general technique of
boundary scans, the pins on the device can be controlled from software, thus
enabling access to most of the logic components on the PCB.


Working principle
-----------------

OpenOCD supports generic access to the boundary scan facilities that are
defined and published for many chips.  Even if the detailed test/debug
specifications are hidden, there usually is a boundary scan definition to aid
in PCB debugging.  This is why it is fruitful to have a generic module to use
such definitions.

The so-called Boundary Scan Definition Language, or BSDL for short, specifies
which registers are accessible over JTAG, and how they are related to pins
that are usually made available externally.  It specifies scan bits to be
inputs, outputs or bidirectional or, very interesting, which internal scan
bits are used to control others; this is often used to set output lines into
high-impedance mode where external signals win over the internally generated
ones.  In other words, it makes pins behave like inputs.

When doing a boundary scan, pin values are clocked into the chip while the
older pin values are clocked out.  While this serial shift process is taking
place, the pins will be held to their old values.  So by sending proper
values to a chip, it is possible to set its external pins to desired values,
and when making another round it is possible to read in the values on input
and high-impedance pins.  All in all, the JTAG interface enables us to
control chips on the PCB which can handle elongated signaling from the
processor chip.

In all this, the internal structure of the processor is no required
knowledge; only its boundary scan definition is, and that is usually public.
There are quicker ways of accessing (say) a flash chip on a bus if the
processor co-operates, but when faced with nothing but the BSDL definition,
this generic approach may be the only chance we have of accessing chips on
the PCB under program control.


Reading flash
-------------

To read the contents of a flash memory, the pins of a processor are set and
reset as decreed by the datasheet of the chip (or our intuition, our
measurements, ...) and specifically we set an address to be read on the
chip's address lines.  We clock it into the chip and apply it to the pins.
The second run of the same process will clock out the value read on the data
pins.

Mostly, a bus uses strobe signals, such as a MEMREAD pulse that temporary
changes from its default setting.  If this is the case, clocking in the
values to the chip happens in a few more stages: first all data, then the
same data with read strobe signals inverted, then the same data with the
strobe back to normal while the data is being clocked out.

The cycle for a read therefore comprises of:

1. Clock all signals to the chip, including address lines but with
   inactive strobe signals;

2. Clock the same to the chip, but now with activated read strobe signals;

3. Clock the same to the chip, with read strobe made inactive again;
   at the same time, clock the read values out of the chip by reading the
   data bits.

Of course, things can be optimised a bit.  Some techniques involve knowledge
of the processor or board, and are unsuitable for a generic BSDL driver, but
others can work.  One general technique is to overlay phase 3 with the next
address's phase 1, by already sending out the next address and data values.
Another possible optimisation is to perform asynchronous reads, and harvest
the bits read by looking at the returned values when they arrive.  This
causes a continuous flow of action from host to target until the end, when
all that remains is to wait for all the have finished.


Writing flash
-------------

TODO -- probably pretty much the same as reading, with the sidenote that a
special protocol such as CFI may be needed to actually change future readout
values.

The optimisations that work for reading cannot all be applied to writing.
First, the overlap between phase 3 and the next phase 1 works by already
preparing the next-cycle address and data bus values, and that is not
generally safe because the write strobe is removed at the same time.
Glitches could cause spurious writes at unpredictable locations, which
is precisely why data and address lines are held stable around strobes.
On the other hand, writing is really one-way traffic from host to target,
so it is quite possible to do that as asynchronously as possible.  Again,
at the end it is possible to wrap up by waiting until the queue has been
fully run.


Performance
-----------

The overall performance of flash chip access through this method depends on
the speeds that can be achieved over thus JTAG interface.  Generally, the
number of bits that constitute a boundary scan must be clocked in several
times for a single operation, so there is quite a bit of overhead.

For example, consider using a 6 MHz interface to access a 1 MB flash at 16
bits, if the total boundary scan contains 114 bits.  Let's assume about 125
bits of data are actually passed around per boundary scan.  Reading takes 3
boundary scans (375 bits) and since the 1 MB flash can be loaded in 16 bit
words, 512*1024 of those boundary scan series must be made (196608000 bits).
At 6 MHz, that would take up 33 seconds.  In practice however, there are
quite a few things to wait for, causing much longer times to do it,
possibly up to an hour.  Good enough for rescue operations, but not a nice
phase in a development-and-test cycle.

Note that the logic of this procedure will usualy require that the chip
being boarded is at rest.  The board hopefuly provides ways of doing that,
possibly  by holding the system reset signal active by pressing a reset
button.  Where supported, the JTAG cable or the boundary scan logic could
be used to achieve a halted system. 



Specification commands
----------------------

The following command creates a target xyz for TAP xy.z::

        target create xyz generic_bsdl -chain-position xy.z

A target continues to read in a BSDL file holding the chip's boundary scan
definition:

        xy.z bsdlfile /path/to/somechip.bsdl

Output and bidirectional bits can be set to their resting state which may be
set, reset or float::

        xy.z force float K L M
        xy.z force set   N O P
        xy.z force reset Q R S(*)

Note the form S(*) which covers all elements of an array, so S(0), S(1), and
so on.  If it is needed to revert these forced settings of pins at some later
stage, then a statement can be issued for that:

        xy.z force none

A few signals must be specified explicitly, to allow control over them by
programs such as memory dumpers; these are the address and data lines::

        xy.z define address A(*)
        xy.z define data D(*)

Strobe signals can be setup for reading and writing operations separately.
The duration of all these strobe signals will last considerably longer than
under live control by the chip.  Strobes are defined as follows::

        xy.z define readstrobe  MEMSEL
        xy.z define writestrobe MEMSEL RD_NOTWR

It is good practice to have read_not_write signals set to a resting state
that represents reading, and only pulse them to writing mode with a strobe.
The same is also true for chip-select or bus-select kind of signals signals.