pipes: add documentation for pipes

Stick with the name "gdb_port" even if this command
can be used for other things(disable, named pipes,
anonymous stdin/out pipe). "port" is correct for
probably more than 90% of use cases, if not more.

Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 77a0ad3b73f7ea19eb7073b7f28f8a1f6d258705..5387082d0be0434ffd6f39bc76d0e5c15135049a 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -1910,12 +1910,29 @@ use the command line @option{-pipe} option.
 
 @deffn {Command} gdb_port [number]
 @cindex GDB server
-Specify or query the first port used for incoming GDB connections.
-The GDB port for the
-first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
+Normally gdb listens to a TCP/IP port, but GDB can also
+communicate via pipes(stdin/out or named pipes). The name
+"gdb_port" stuck because it covers probably more than 90% of
+the normal use cases.
+
+No arguments reports GDB port. "pipe" means listen to stdin 
+output to stdout, an integer is base port number, "disable"
+disables the gdb server.
+
+When using "pipe", also use log_output to redirect the log
+output to a file so as not to flood the stdin/out pipes.
+
+The -p/--pipe option is deprecated and a warning is printed
+as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log".
+
+Any other string is interpreted as named pipe to listen to. 
+Output pipe is the same name as input pipe, but with 'o' appended,
+e.g. /var/gdb, /var/gdbo.
+                               
+The GDB port for the first target will be the base port, the 
+second target will listen on gdb_port + 1, and so on.
 When not specified during the configuration stage,
 the port @var{number} defaults to 3333.
-When specified as zero, GDB remote access ports are not activated.
 @end deffn
 
 @deffn {Command} tcl_port [number]
@@ -1925,7 +1942,7 @@ output from the Tcl engine.
 Intended as a machine interface.
 When not specified during the configuration stage,
 the port @var{number} defaults to 6666.
-When specified as zero, this port is not activated.
+
 @end deffn
 
 @deffn {Command} telnet_port [number]

diff --git a/src/server/gdb_server.c b/src/server/gdb_server.c
index 7026ff21871869e5f2883cb891ee123451ecafa1..518090265ae9a2449f877835c4e9eff51b35c44c 100644 (file)
--- a/src/server/gdb_server.c
+++ b/src/server/gdb_server.c
@@ -2545,9 +2545,13 @@ static const struct command_registration gdb_command_handlers[] = {
                .name = "gdb_port",
                .handler = handle_gdb_port_command,
                .mode = COMMAND_ANY,
-               .help = "Display or specify base port on which to listen "
-                       "for incoming GDB connections.  "
-                       "No arguments reports GDB port; zero disables.",
+               .help = "Normally gdb listens to a TCP/IP port. Each subsequent GDB "
+                               "server listens for the next port number after the "
+                               "base port number specified. "
+                               "No arguments reports GDB port. \"pipe\" means listen to stdin "
+                               "output to stdout, an integer is base port number, \"disable\" disables "
+                               "port. Any other string is are interpreted as named pipe to listen to. "
+                               "Output pipe is the same name as input pipe, but with 'o' appended.",
                .usage = "[port_num]",
        },
        {

diff --git a/src/server/tcl_server.c b/src/server/tcl_server.c
index 613eb23f9260190b0b7c56434e82a3acbeb24026..16710860614c708f21ddb24121aa9686cd90ef91 100644 (file)
--- a/src/server/tcl_server.c
+++ b/src/server/tcl_server.c
@@ -183,7 +183,7 @@ static const struct command_registration tcl_command_handlers[] = {
                .mode = COMMAND_CONFIG,
                .help = "Specify port on which to listen "
                        "for incoming Tcl syntax.  "
-                       "No arguments reports Tcl port; zero disables.",
+                       "Read help on 'gdb_port'.",
                .usage = "[port_num]",
        },
        COMMAND_REGISTRATION_DONE

diff --git a/src/server/telnet_server.c b/src/server/telnet_server.c
index 00b4b5d26b2013929aa23fbfbedfb1fdfcd11f95..98e86160a3d5d34201090caae7c69f2223cd58bb 100644 (file)
--- a/src/server/telnet_server.c
+++ b/src/server/telnet_server.c
@@ -619,7 +619,7 @@ static const struct command_registration telnet_command_handlers[] = {
                .mode = COMMAND_ANY,
                .help = "Specify port on which to listen "
                        "for incoming telnet connections.  "
-                       "No arguments reports telnet port; zero disables.",
+                       "Read help on 'gdb_port'.",
                .usage = "[port_num]",
        },
        COMMAND_REGISTRATION_DONE