From ff647e6bb4180a7c376b61caeb14951ba84d5717 Mon Sep 17 00:00:00 2001
From: David Brownell <dbrownell@users.sourceforge.net>
Date: Sat, 9 Jan 2010 21:56:11 -0800
Subject: [PATCH] parport (mostly) doc fixes

The "parport_port" commands generally don't *require* a port_number;
they're of the "apply any parameter, then print result" variety.  Update
the User's Guide accordingly.

Some of those commands are intended to be write-once: parport_port,
and parport_cable.  Say so.

Use proper EBNF for the parport_write_on_exit parameter.

Parport address 0xc8b8 is evidently mutant.  Say so in the "parport.cfg"
file, to avoid breaking anyone with that mutant config.  But update the
User's Guide to include a sane example for the LP2 port.

Finally document the "presto_serial" command.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
---
 doc/openocd.texi          | 32 +++++++++++++++++++-------------
 tcl/interface/parport.cfg |  2 ++
 2 files changed, 21 insertions(+), 13 deletions(-)

diff --git a/doc/openocd.texi b/doc/openocd.texi
index f8956a31..6466d6dc 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2073,9 +2073,11 @@ $_TARGETNAME configure -event reset-assert \
 Gateworks GW16012 JTAG programmer.
 This has one driver-specific command:
 
-@deffn {Config Command} {parport_port} number
-Specifies either the address of the I/O port (default: 0x378 for LPT1) or
-the number of the @file{/dev/parport} device.
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
 @end deffn
 @end deffn
 
@@ -2094,7 +2096,8 @@ These interfaces have several commands, used to configure the driver
 before initializing the JTAG scan chain:
 
 @deffn {Config Command} {parport_cable} name
-The layout of the parallel port cable used to connect to the target.
+Set the layout of the parallel port cable used to connect to the target.
+This is a write-once setting.
 Currently valid cable @var{name} values include:
 
 @itemize @minus
@@ -2122,9 +2125,11 @@ several clones, such as the Olimex ARM-JTAG
 @end itemize
 @end deffn
 
-@deffn {Config Command} {parport_port} number
-Either the address of the I/O port (default: 0x378 for LPT1) or the number of
-the @file{/dev/parport} device
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
 
 When using PPDEV to access the parallel port, use the number of the parallel port:
 @option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
@@ -2167,25 +2172,26 @@ match for the jtag_khz rate you specified; be conservative.
 @end quotation
 @end deffn
 
-@deffn {Config Command} {parport_write_on_exit} (on|off)
+@deffn {Config Command} {parport_write_on_exit} (@option{on}|@option{off})
 This will configure the parallel driver to write a known
-cable-specific value to the parallel interface on exiting OpenOCD
+cable-specific value to the parallel interface on exiting OpenOCD.
 @end deffn
 
 For example, the interface configuration file for a
-classic ``Wiggler'' cable might look something like this:
+classic ``Wiggler'' cable on LPT2 might look something like this:
 
 @example
 interface parport
-parport_port 0xc8b8
+parport_port 0x278
 parport_cable wiggler
 @end example
 @end deffn
 
 @deffn {Interface Driver} {presto}
 ASIX PRESTO USB JTAG programmer.
-@c command:	presto_serial str
-@c     sets serial number
+@deffn {Config Command} {presto_serial} serial_string
+Configures the USB serial number of the Presto device to use.
+@end deffn
 @end deffn
 
 @deffn {Interface Driver} {rlink}
diff --git a/tcl/interface/parport.cfg b/tcl/interface/parport.cfg
index 2a2668d5..22be8f35 100644
--- a/tcl/interface/parport.cfg
+++ b/tcl/interface/parport.cfg
@@ -1,6 +1,8 @@
 #
 # Parallel port wiggler (many clones available) on port 0xc8b8
 #
+# REVISIT this address seems very wrong.
+# Surely 0x378/LPT1 or 0x278/LPT2 ...
 
 interface parport
 parport_port 0xc8b8
-- 
2.39.5