update command handler documentation

Adds sections on command registration and chaining, giving an overview
to developers that want to use these features.

add 'testee' target type

Alliteration aside, this should provide the final piece of the puzzle
for developers that want to get started writing a new target type.
In this way, it also seeks to complement the 'dummy' interface driver
and 'faux' NOR flash driver.

improve command handling examples

Removes hello and foo commands from top-level registration.  Instead,
the dummy interface driver and faux flash driver have been augmented
to register these commands as sub-commands.

add script_command_run helper

Eliminates duplicated code in script_command and handle_unknown_command.
Fixes bug with duplicated help output generated by placeholder commands.

encapsulate and re-use log capture, retval setup

Factors log capture while running script commands, eliminating
duplicated code between script_command and jim_capture.  Factors
setting a command's Jim "retval" into a new helper as well.

Using these new helpers in the new unknown command handler's
fixes possible regressions caused by these bits being missing.

combine help and usage command handlers

Remove duplicated handler code by checking the running command name.

improve usage and help command output

Rewrite formatting code in C, removing last remenants of TCL help code.
Sinificantly improves the readability by using smarter indent and wrap.

allow scripts to update usage information

The add_usage_text command uses the same C handler, which was updated
to support its new polymorphic role.  This patch updates the two script
commands that needed this support: 'find' and 'script'.

httpd: use register_commands()

Updates httpd_start() to use register_commands() for 'readform' and
'writeform' commands.  Adds server/httpd.h to export the new signatures
for this function (and httpd_stop), which allows removing the obsoleted
declarations inside openocd.c.

add jim_handler to command_registration

Adding jim_handler field to command_registration allows removing the
register_jim helper.  All command registrations now go through the
register_command{,s}() functions.

refactor command_new to use command_registration

Save stack space: use a struct.  Makes it easier to add new parameters.

remove register_commands from etm_capture_driver

Converts callback to an array of command_registration records.
Moves oocd_trace driver definition to end of file to eliminate
useless forward declaration.

remove target_type register_command callback

Uses chaining of command_registration structures to eliminate all
target_type register_callback routines.  Exports the command_handler
registration arrays for those target types that are used by others.

xscale: use register_commands()

trace: use register_commands()

target_request: use register_commands()

target: use register_commands()

oocd_trace: use register_commands()

etm_dummy: use register_commands()

etm: use register_commands()

etb: use register_commands()

cortex_m3: use register_commands()

cortex_a8: use register_commands()

armv7m: use register_commands()

armv7a: use register_commands()

armv4_5: use register_commands()

arm9tdmi: use register_commands()

arm966e: use register_commands()

arm926ejs: use register_commands()

arm920t: use register_commands()

arm7_9_common: use register_commands()

arm720t: use register_commands()

arm11: use register_commands()

remove nand_controller->register_callbacks

Replace flash_driver callback with pointer to command_registration.
Eliminates all related routines and allows drivers to omit commands.

remove flash_driver->register_callbacks

Replace flash_driver callback with pointer to command_registration.
Eliminates all related routines and allows drivers to omit commands.

tms470: use register_commands()

str9xpec: use register_commands()

str9x: use register_commands()

str7x: use register_commands()

stm32x: use register_commands()

stellaris: use register_commands()

pic32mx: use register_commands()

nand: use register_commands()

Eliminates 'nand_cmd' global variable.

mflash: use register_commands()

lpc3180_nand_controller: use register_commands()

lpc2900: use register_commands()

lpc2000: use register_commands()

flash: use register_commands()

Eliminates 'flash_cmd' global variable.

ecos: use register_commands()

cfi: use register_commands()

avrf: use register_commands()

at91sam7: use register_commands()

at91sam3: use register_commands()

remove register_callbacks from jtag interface

Changes the jtag_interface->register_callbacks field to a list of
commands to be registered.  Changes callback to invocation of
register_commands() with that command registration list.  Removes all
JTAG interface driver register_command callback functions, which the
previous commits had converted into identical calls.

vsllink: use register_commands()

Use register_commands() with command registration array.

jtag: use register_commands()

Use register commands with command registration array.

presto: use register_commands()

Use register_commands() with command registration array.

parport: use register_commands()

Use register_commands() with a command registration array.

jlink: use register_commands()

Use register_commands() with command registration array.

gw16012: use register_commands()

Use register_commands() with command registration array.

ft2232: use register_commands()

Use register_commands() with a command registration array.

at91rm9200: use register_commands()

Use register_commands() with command registration array.
---
This module was broken by previous changes, but no one has complained.
Are there still users for this modules?

arm-jtag-ew: use register_commands()

Uses register_commands() with command registration array.

amt_jtagaccel: use register_commands()

Use register_commands() with command_registration array.

pld: use static registration instead of callback

Remove register_callbacks from pld_device structure, using an array
of command_registration records instead.

pld: use register_commands()

Updates core PLD and virtex2 commands to use register_commands().

{,x}svf: use register_commands()

Use register_commands() for registering {,x}svf commands.

server: use register_commands

Converts server directory to use new command registration paradigm.

log: use register_commands()

Use register_commands() for logging callbacks.  Improve help and add
proper usage.

ioutil: use register_commands()

Use table instead of individual calls.  Add proper usage information.

openocd: use register_commands()

Use register_commands() for top-level version and init command.

demonstrate chaining with foo commands

Use the new command registration chaining capabilities to eliminate
the foo_register_commands helper, folding its remaining command
handler setup into the hello_command_handlers registration array.

hello: use register_commands()

Use new register_commands() with command registration table.

rewrite 'unknown' command dispatching in C

Rewrite the magical 'unknown' command in C as a Jim handler, allowing
it to dispatch commands to any level in the tree.

add public API for locating commands

Allow other modules to find a command, primarily for the purpose of
registering and unregistering subcommands.

refactor script_command context grabbing

Move command context acquisition to current_command_context() for re-use.

add command registration chaining

Adds the ability to chain registration structures.  Modules can define a
command with the 'chain' and 'num_chain' fields defined in their
registration table, and the register_commands() function will initialize
these commands.  If the registration record creates a new command, then
the chained commands are created under it; otherwise, they are created
in the same context as the other commands (i.e. the parent argument).

more command registration refactoring

Split out the handler registration into its own function, and add a
few obviously missing NULL pointer error checking.

command: use register_commands for handlers

Use register_commands() to register low-level command handlers,
adding a builtin_command_handlers declaration that is easy to understand.
Splits help and usage information into their appropriate fields.

add command usage, separate from help

Adds the usage command, to display usage information for commands.
The output for this command will remain erronenously empty until
commands are updated to use these new coventions.

add register_commands for batch registration

The register_commands API takes multiple commands in one call, allowing
modules to declare and pass a much simpler (and more explicit) array of
command_registration records.

add struct command_registration

Add a structure to encapsulate command registration information, rather
than passing them all as parameters.  Enables further API changes that
require additional required or optional parameters.

Updates the register_command API and COMMAND_REGISTER macro to use it,
along with their documentation.

use COMMAND_REGISTER macro

Replaces direct calls to register_command() with a macro, to allow
its parameters to be changed and callers updated in phases.

add COMMAND_REGISTER macro

Provides a migration path for the widely used register_command API,
which needs to be updated to provide new functionality.

This macro allows the API to change without having to update all of its
callers at the same time.

improve startup tcl scripts

Fix a couple of layering violations missed in the last round.
Add missing comment headers.

Cortex-A8: avoid DSCR reads

There was a lot of needless handshaking overhead in the current
Cortex-A8 DCC/ITR operations, since the status read by each step
was discarded rather than letting the next step know it.

This shrinks the handshaking by:  (a) passing status along from
previous steps, avoiding re-fetching; which enables the big win
(b) relying on a useful invariant:  that the DSCR_INSTR_COMP bit
is set after every call to a DPM method.

A "reg sp_usr" call previously took 17 flushes; now it takes just 9.
This visibly speeds common operations like entry to debug state and
stepping, as well as "arm reg" and so on.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

Cortex-A8: hook up DPM

This replaces two versions of register access functions.  One
was commented out, and seemed to have uncertain intent.  The
other was fairly new, and helped motivate the DPM framework
once I observed that the ARM11 was doing the very same ops.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

Cortex-A8: implement DPM

This implements the DPM interface for Cortex-A8 cores.  It
also adds a synchronization operation to the DPM framework,
which is needed by the Cortex-A8 after CPSR writes.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

Cortex-A8: minor cleanup

Make various functions static, add some comments, report
vector catch as a flavor of DBG_REASON_BREAKPOINT, get
rid of needless/undesirable ARMV4_5_CORE_REG_MODE, etc.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

improve alloc_vprintf

The previous implementation was unnecessarily complex. Get rid of the loops,
let vsnprintf() tell us directly how much storage we need and allocate that. A
second pass writes the actual string. Also add a va_end() that was missing.
This should be much faster for large strings and less wasteful for small ones.

A quirk that has been retained is that some callers patch in a newline at the
end of the returned string and depend on alloc_vprintf to allocate at least
one byte extra.

Signed-off-by: Andreas Fritiofson <andreas.fritiofson@gmail.com>
Signed-off-by: Zachary T Welch <zw@superlucidity.net>

fix doxygen build

Update build rules to skip the PDF unless the TeX has been created.
Also, fixes a warning regarding pattern rules being a GNU make trick.

jlink: rewrite to use jtag_usb_open

Rewrite jlink_usb_open to use jtag_usb_open helper.

jlink: remove superfluous indentation

Rewrite logic to remove indentation in jlink_usb_open, in prep
for further surgery.

rlink: use jtag_usb_open helper

Rewrite rlink_init routine to use jtag_usb_open helper.  Eliminates
some spurious calls to exit().

Wraps a tremendously long line of comment to fit 80 columns too.

rlink: eliminate spurious indentation

Rework rlink_init to use less indentation.  Best viewed with diff -w.

vsllink: rewrite to use jtag_usb_open

Rewrite vsllink_usb_open to use jtag_usb_open helper.

Eliminates spurious calls to exit().

usbprog: use jtag_usb_open

Rewrite usbprob_jtag_open to use jtag_usb_open helper.

arm-jtag-ew: use jtag_usb_open

Rewrite armjtagwe_usb_open to use jtag_usb_open.

add jtag/usb_common.[ch] files

Begins to consolidate code used by several USB JTAG interfaces.
This first patch provides the required build system changes and
a common jtag_usb_open routine, which will replace the guts for
probing the busses and devices for possible VID/PID matches.
The following patches convert each driver to use it.

ARM11: remove old R0..R15/CPSR code

This finishes the basic switchover to the new register code,
for everything except the debug registers.  (And maybe we
shouldn't have a cache for *those* which works this way...)

The context save/restore code now uses the new code, but
it's in a slightly different sequence.  That should be fine
since the R0/PC/CPSR stuff is all that really matters (and
if we can update those, we can update the rest).

Now there's no longer a way any code can be confused about
which copy of "r1" (etc) to use.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>