[Qemu-devel] [PATCH] Documentation: Add documentation for -chardev

[Qemu-devel] [PATCH] Documentation: Add documentation for -chardev

[Matthew Booth]

This patch adds documentation for -chardev. Please note that I am not the author
of the -chardev code, so please read it carefully!

[Qemu-devel] [PATCH] Documentation: Add documentation for -chardev

[Matthew Booth]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 9595 bytes --]

Adds documentation for all -chardev backends.
---
 qemu-options.hx |  254 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 251 insertions(+), 3 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index d78b738..bc447a5 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1085,6 +1085,257 @@ is activated if no @option{-net} options are provided.
 @end table
 ETEXI
 
+DEFHEADING()
+
+DEFHEADING(Character device options:)
+
+DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
+    "-chardev null\n"
+    "                A void device. This device will not emit any data, and will\n"
+    "                drop any data it receives.\n"
+    "\n"
+    "-chardev socket[,id=id][TCP options or unix options][,server][,nowait][,telnet]\n"
+    "                TCP options:  port=host[,host=host][,to=to][,ipv4][,ipv6]\n"
+    "                              [,nodelay]\n"
+    "\n"
+    "                unix options: path=path\n"
+    "\n"
+    "                Create a two-way stream socket, which can be either a TCP or a\n"
+    "\n"
+    "-chardev udp[,id=id][,host=host],port=port[,localaddr=localaddr]\n"
+    "            [,localport=localport][,ipv4][,ipv6]\n"
+    "                Sends all traffic from the guest to a remote host over UDP.\n"
+    "\n"
+    "-chardev msmouse[,id=id]\n"
+    "                Forward QEMU’s emulated msmouse events to the guest.\n"
+    "\n"
+    "-chardev vc[,id=id]\n"
+    "                Connect to a QEMU text console.\n"
+    "\n"
+    "-chardev file[,id=id],path=path\n"
+    "                Log all traffic received from the guest to a file.\n"
+    "\n"
+    "-chardev pipe[,id=id],path=path\n"
+#ifdef _WIN32
+    "                Create a duplex pipe at \\.pipe\path.\n"
+#else
+    "                Connect to 2 pipes called path.in and path.out.\n"
+#endif
+    "\n"
+#ifdef _WIN32
+    "-chardev console[,id=id]\n"
+    "                Send traffic from the guest to QEMU’s standard output.\n"
+    "\n"
+    "-chardev serial[,id=id],path=path\n"
+    "                Send traffic from the guest to a serial device on the host.\n"
+#else
+    "-chardev pty[,id=id]\n"
+    "                Create a new pseudo-terminal on the host and connect to it.\n"
+    "\n"
+    "-chardev stdio[,id=id]\n"
+    "                Connect to standard input and standard output of the qemu\n"
+    "                process.\n"
+#endif
+    "\n"
+#ifdef CONFIG_BRLAPI
+    "-chardev braille[,id=id]\n"
+    "                Connect to a local BrlAPI server.\n"
+    "\n"
+#endif
+    "-chardev tty[,id=id],path=path\n"
+    "                Connect to a local tty device.\n"
+    "\n"
+    "-chardev parport[,id=id],path=path\n"
+    "                Connect to a local parallel port.\n")
+
+STEXI
+
+The general form of a character device option is:
+@table @option
+
+@item -chardev @var{backend} [,id=@var{id}] [,@var{options}]
+
+Backend is one of:
+@option{null},
+@option{socket},
+@option{udp},
+@option{msmouse},
+@option{vc},
+@option{file},
+@option{pipe},
+@option{console},
+@option{serial},
+@option{pty},
+@option{stdio},
+@option{braille},
+@option{tty},
+@option{parport}.
+The specific backend will determine the applicable options.
+
+All devices can be given an id, which can be any string up to 127 characters
+long. It is used to uniquely identify this device in other command line
+directives.
+
+Options to each backend are described below.
+
+@item -chardev null
+A void device. This device will not emit any data, and will drop any data it
+receives. The null backend does not take any options.
+
+@item -chardev socket [,id=@var{id}] [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
+
+Create a two-way stream socket, which can be either a TCP or a unix socket. A
+unix socket will be created if @option{path} is specified. Behaviour is
+undefined if TCP options are specified for a unix socket.
+
+@option{server} specifies that the socket shall be a listening socket.
+
+@option{nowait} specifies that QEMU should not block waiting for a client to
+connect to a listening socket.
+
+@option{telnet} specifies that traffic on the socket should interpret telnet
+escape sequences.
+
+TCP and unix socket options are given below:
+
+@table @option
+
+@item TCP options: port=@var{host} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
+
+@option{host} for a listening socket specifies the local address to be bound.
+For a connecting socket species the remote host to connect to. @option{host} is
+optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
+
+@option{port} for a listening socket specifies the local port to be bound. For a
+connecting socket specifies the port on the remote host to connect to.
+@option{port} can be given as either a port number or a service name.
+@option{port} is required.
+
+@option{to} is only relevant to listening sockets. If it is specified, and
+@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
+to and including @option{to} until it succeeds. @option{to} must be specified
+as a port number.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the socket may use either protocol.
+
+@option{nodelay} disables the Nagle algorithm.
+
+@item unix options: path=@var{path}
+
+@option{path} specifies the local path of the unix socket. @option{path} is
+required.
+
+@end table
+
+@item -chardev udp [,id=@var{id}] [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
+
+Sends all traffic from the guest to a remote host over UDP.
+
+@option{host} specifies the remote host to connect to. If not specified it
+defaults to @code{localhost}.
+
+@option{port} specifies the port on the remote host to connect to. @option{port}
+is required.
+
+@option{localaddr} specifies the local address to bind to. If not specified it
+defaults to @code{0.0.0.0}.
+
+@option{localport} specifies the local port to bind to. If not specified any
+available local port will be used.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the device may use either protocol.
+
+@item -chardev msmouse [,id=@var{id}]
+
+Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
+take any options.
+
+@item -chardev vc [,id=@var{id}]
+
+Connect to a QEMU text console. @option{vc} does not take any options.
+
+@item -chardev file [,id=@var{id}] ,path=@var{path}
+
+Log all traffic received from the guest to a file.
+
+@option{path} specifies the path of the file to be opened. This file will be
+created if it does not already exist, and overwritten if it does. @option{path}
+is required.
+
+@item -chardev pipe [,id=@var{id}] ,path=@var{path}
+
+Create a two-way connection to the guest. The behaviour differs slightly between
+Windows hosts and other hosts:
+
+On Windows, a single duplex pipe will be created at
+@file{\\.pipe\@option{path}}.
+
+On other hosts, 2 pipes will be created called @file{@option{path}.in} and
+@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
+received by the guest. Data written by the guest can be read from
+@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
+be present.
+
+@option{path} forms part of the pipe path as described above. @option{path} is
+required.
+
+@item -chardev console [,id=@var{id}]
+
+Send traffic from the guest to QEMU's standard output. @option{console} does not
+take any options.
+
+@option{console} is only available on Windows hosts.
+
+@item -chardev serial [,id=@var{id}] ,path=@option{path}
+
+Send traffic from the guest to a serial device on the host.
+
+@option{serial} is
+only available on Windows hosts.
+
+@option{path} specifies the name of the serial device to open.
+
+@item -chardev pty [,id=@var{id}]
+
+Create a new pseudo-terminal on the host and connect to it. @option{pty} does
+not take any options.
+
+@option{pty} is not available on Windows hosts.
+
+@item -chardev stdio [,id=@var{id}]
+Connect to standard input and standard output of the qemu process.
+@option{stdio} does not take any options. @option{stdio} is not available on
+Windows hosts.
+
+@item -chardev braille [,id=@var{id}]
+
+Connect to a local BrlAPI server. @option{braille} does not take any options.
+
+@item -chardev tty [,id=@var{id}] ,path=@var{path}
+
+Connect to a local tty device.
+
+@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
+DragonFlyBSD hosts.
+
+@option{path} specifies the path to the tty. @option{path} is required.
+
+@item -chardev parport [,id=@var{id}] ,path=@var{path}
+
+Connect to a local parallel port.
+
+@option{path} specifies the path to the parallel port device. @option{path} is
+required.
+
+@end table
+ETEXI
+
+DEFHEADING()
+
+DEFHEADING(Bluetooth(R) options:)
+
 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
     "\n" \
     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
@@ -1097,7 +1348,6 @@ DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
     "-bt device:dev[,vlan=n]\n" \
     "                emulate a bluetooth device 'dev' in scatternet 'n'\n")
 STEXI
-Bluetooth(R) options:
 @table @option
 
 @item -bt hci[...]
@@ -1206,8 +1456,6 @@ STEXI
 @table @option
 ETEXI
 
-DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, \
-    "-chardev spec   create unconnected chardev\n")
 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
     "-serial dev     redirect the serial port to char device 'dev'\n")
 STEXI
-- 
1.6.2.5

[Qemu-devel] [PATCH] Documentation: Add documentation for -chardev

[Matthew Booth]

Noticed that I'd omitted id= from -chardev null. Updated patch adds it.

[Qemu-devel] [PATCH] Documentation: Add documentation for -chardev

[Matthew Booth]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 9618 bytes --]

Adds documentation for all -chardev backends.
---
 qemu-options.hx |  254 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 251 insertions(+), 3 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index d78b738..0d74b48 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1085,6 +1085,257 @@ is activated if no @option{-net} options are provided.
 @end table
 ETEXI
 
+DEFHEADING()
+
+DEFHEADING(Character device options:)
+
+DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
+    "-chardev null[,id=id]\n"
+    "                A void device. This device will not emit any data, and will\n"
+    "                drop any data it receives.\n"
+    "\n"
+    "-chardev socket[,id=id][TCP options or unix options][,server][,nowait][,telnet]\n"
+    "                TCP options:  port=host[,host=host][,to=to][,ipv4][,ipv6]\n"
+    "                              [,nodelay]\n"
+    "\n"
+    "                unix options: path=path\n"
+    "\n"
+    "                Create a two-way stream socket, which can be either a TCP or a\n"
+    "\n"
+    "-chardev udp[,id=id][,host=host],port=port[,localaddr=localaddr]\n"
+    "            [,localport=localport][,ipv4][,ipv6]\n"
+    "                Sends all traffic from the guest to a remote host over UDP.\n"
+    "\n"
+    "-chardev msmouse[,id=id]\n"
+    "                Forward QEMU’s emulated msmouse events to the guest.\n"
+    "\n"
+    "-chardev vc[,id=id]\n"
+    "                Connect to a QEMU text console.\n"
+    "\n"
+    "-chardev file[,id=id],path=path\n"
+    "                Log all traffic received from the guest to a file.\n"
+    "\n"
+    "-chardev pipe[,id=id],path=path\n"
+#ifdef _WIN32
+    "                Create a duplex pipe at \\.pipe\path.\n"
+#else
+    "                Connect to 2 pipes called path.in and path.out.\n"
+#endif
+    "\n"
+#ifdef _WIN32
+    "-chardev console[,id=id]\n"
+    "                Send traffic from the guest to QEMU’s standard output.\n"
+    "\n"
+    "-chardev serial[,id=id],path=path\n"
+    "                Send traffic from the guest to a serial device on the host.\n"
+#else
+    "-chardev pty[,id=id]\n"
+    "                Create a new pseudo-terminal on the host and connect to it.\n"
+    "\n"
+    "-chardev stdio[,id=id]\n"
+    "                Connect to standard input and standard output of the qemu\n"
+    "                process.\n"
+#endif
+    "\n"
+#ifdef CONFIG_BRLAPI
+    "-chardev braille[,id=id]\n"
+    "                Connect to a local BrlAPI server.\n"
+    "\n"
+#endif
+    "-chardev tty[,id=id],path=path\n"
+    "                Connect to a local tty device.\n"
+    "\n"
+    "-chardev parport[,id=id],path=path\n"
+    "                Connect to a local parallel port.\n")
+
+STEXI
+
+The general form of a character device option is:
+@table @option
+
+@item -chardev @var{backend} [,id=@var{id}] [,@var{options}]
+
+Backend is one of:
+@option{null},
+@option{socket},
+@option{udp},
+@option{msmouse},
+@option{vc},
+@option{file},
+@option{pipe},
+@option{console},
+@option{serial},
+@option{pty},
+@option{stdio},
+@option{braille},
+@option{tty},
+@option{parport}.
+The specific backend will determine the applicable options.
+
+All devices can be given an id, which can be any string up to 127 characters
+long. It is used to uniquely identify this device in other command line
+directives.
+
+Options to each backend are described below.
+
+@item -chardev null [,id=@var{id}]
+A void device. This device will not emit any data, and will drop any data it
+receives. The null backend does not take any options.
+
+@item -chardev socket [,id=@var{id}] [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
+
+Create a two-way stream socket, which can be either a TCP or a unix socket. A
+unix socket will be created if @option{path} is specified. Behaviour is
+undefined if TCP options are specified for a unix socket.
+
+@option{server} specifies that the socket shall be a listening socket.
+
+@option{nowait} specifies that QEMU should not block waiting for a client to
+connect to a listening socket.
+
+@option{telnet} specifies that traffic on the socket should interpret telnet
+escape sequences.
+
+TCP and unix socket options are given below:
+
+@table @option
+
+@item TCP options: port=@var{host} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
+
+@option{host} for a listening socket specifies the local address to be bound.
+For a connecting socket species the remote host to connect to. @option{host} is
+optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
+
+@option{port} for a listening socket specifies the local port to be bound. For a
+connecting socket specifies the port on the remote host to connect to.
+@option{port} can be given as either a port number or a service name.
+@option{port} is required.
+
+@option{to} is only relevant to listening sockets. If it is specified, and
+@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
+to and including @option{to} until it succeeds. @option{to} must be specified
+as a port number.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the socket may use either protocol.
+
+@option{nodelay} disables the Nagle algorithm.
+
+@item unix options: path=@var{path}
+
+@option{path} specifies the local path of the unix socket. @option{path} is
+required.
+
+@end table
+
+@item -chardev udp [,id=@var{id}] [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
+
+Sends all traffic from the guest to a remote host over UDP.
+
+@option{host} specifies the remote host to connect to. If not specified it
+defaults to @code{localhost}.
+
+@option{port} specifies the port on the remote host to connect to. @option{port}
+is required.
+
+@option{localaddr} specifies the local address to bind to. If not specified it
+defaults to @code{0.0.0.0}.
+
+@option{localport} specifies the local port to bind to. If not specified any
+available local port will be used.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the device may use either protocol.
+
+@item -chardev msmouse [,id=@var{id}]
+
+Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
+take any options.
+
+@item -chardev vc [,id=@var{id}]
+
+Connect to a QEMU text console. @option{vc} does not take any options.
+
+@item -chardev file [,id=@var{id}] ,path=@var{path}
+
+Log all traffic received from the guest to a file.
+
+@option{path} specifies the path of the file to be opened. This file will be
+created if it does not already exist, and overwritten if it does. @option{path}
+is required.
+
+@item -chardev pipe [,id=@var{id}] ,path=@var{path}
+
+Create a two-way connection to the guest. The behaviour differs slightly between
+Windows hosts and other hosts:
+
+On Windows, a single duplex pipe will be created at
+@file{\\.pipe\@option{path}}.
+
+On other hosts, 2 pipes will be created called @file{@option{path}.in} and
+@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
+received by the guest. Data written by the guest can be read from
+@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
+be present.
+
+@option{path} forms part of the pipe path as described above. @option{path} is
+required.
+
+@item -chardev console [,id=@var{id}]
+
+Send traffic from the guest to QEMU's standard output. @option{console} does not
+take any options.
+
+@option{console} is only available on Windows hosts.
+
+@item -chardev serial [,id=@var{id}] ,path=@option{path}
+
+Send traffic from the guest to a serial device on the host.
+
+@option{serial} is
+only available on Windows hosts.
+
+@option{path} specifies the name of the serial device to open.
+
+@item -chardev pty [,id=@var{id}]
+
+Create a new pseudo-terminal on the host and connect to it. @option{pty} does
+not take any options.
+
+@option{pty} is not available on Windows hosts.
+
+@item -chardev stdio [,id=@var{id}]
+Connect to standard input and standard output of the qemu process.
+@option{stdio} does not take any options. @option{stdio} is not available on
+Windows hosts.
+
+@item -chardev braille [,id=@var{id}]
+
+Connect to a local BrlAPI server. @option{braille} does not take any options.
+
+@item -chardev tty [,id=@var{id}] ,path=@var{path}
+
+Connect to a local tty device.
+
+@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
+DragonFlyBSD hosts.
+
+@option{path} specifies the path to the tty. @option{path} is required.
+
+@item -chardev parport [,id=@var{id}] ,path=@var{path}
+
+Connect to a local parallel port.
+
+@option{path} specifies the path to the parallel port device. @option{path} is
+required.
+
+@end table
+ETEXI
+
+DEFHEADING()
+
+DEFHEADING(Bluetooth(R) options:)
+
 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
     "\n" \
     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
@@ -1097,7 +1348,6 @@ DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
     "-bt device:dev[,vlan=n]\n" \
     "                emulate a bluetooth device 'dev' in scatternet 'n'\n")
 STEXI
-Bluetooth(R) options:
 @table @option
 
 @item -bt hci[...]
@@ -1206,8 +1456,6 @@ STEXI
 @table @option
 ETEXI
 
-DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, \
-    "-chardev spec   create unconnected chardev\n")
 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
     "-serial dev     redirect the serial port to char device 'dev'\n")
 STEXI
-- 
1.6.2.5

[Qemu-devel] Re: [PATCH] Documentation: Add documentation for -chardev

[Gerd Hoffmann]

On 10/29/09 17:56, Matthew Booth wrote:
> +DEFHEADING()
> +
> +DEFHEADING(Character device options:)
> +
> +DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
> +    "-chardev null[,id=id]\n"
> +    "                A void device. This device will not emit any data, and will\n"
> +    "                drop any data it receives.\n"

I'd try to keep this shorter to not bloat the -help text.  Just list the 
options, like this:

-chardev null,id=id
-chardev socket,id=id,path=path[,...]           (unix)
-chardev socket,id=id,port=port[,...]           (tcp)
-chardev udp,...

maybe?  The detailed descriptions are in the man-page.

Oh, and id is *not* optional (would be pointless as you would have no 
way to use the chardev), so it shouldn't be listed in brackets.

> +STEXI
> +
> +The general form of a character device option is:
> +@table @option
> +
> +@item -chardev @var{backend} [,id=@var{id}] [,@var{options}]

Same here.

> +@item -chardev vc [,id=@var{id}]
> +
> +Connect to a QEMU text console. @option{vc} does not take any options.

It takes options for the scren size: width+height (pixels) or cols+rows 
(chars) (see console.c).

Otherwise the patch looks fine.

Thanks for doing this,
   Gerd

[Qemu-devel] Re: [PATCH] Documentation: Add documentation for -chardev

[Matthew Booth]

[-- Attachment #1: Type: text/plain, Size: 1578 bytes --]

On 30/10/09 09:17, Gerd Hoffmann wrote:
> On 10/29/09 17:56, Matthew Booth wrote:
>> +DEFHEADING()
>> +
>> +DEFHEADING(Character device options:)
>> +
>> +DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
>> + "-chardev null[,id=id]\n"
>> + " A void device. This device will not emit any data, and will\n"
>> + " drop any data it receives.\n"
>
> I'd try to keep this shorter to not bloat the -help text. Just list the
> options, like this:
>
> -chardev null,id=id
> -chardev socket,id=id,path=path[,...] (unix)
> -chardev socket,id=id,port=port[,...] (tcp)
> -chardev udp,...
>
> maybe? The detailed descriptions are in the man-page.

Done

>
> Oh, and id is *not* optional (would be pointless as you would have no
> way to use the chardev), so it shouldn't be listed in brackets.

I thought as much, although the code doesn't look as though it'll 
explode if id isn't set. I've updated to indicate it's required.

>> +STEXI
>> +
>> +The general form of a character device option is:
>> +@table @option
>> +
>> +@item -chardev @var{backend} [,id=@var{id}] [,@var{options}]
>
> Same here.
>
>> +@item -chardev vc [,id=@var{id}]
>> +
>> +Connect to a QEMU text console. @option{vc} does not take any options.
>
> It takes options for the scren size: width+height (pixels) or cols+rows
> (chars) (see console.c).

Ah, the path to those wasn't quite so straightforward :) Updated.

New patch attached.

Matt
-- 
Matthew Booth, RHCA, RHCSS
Red Hat Engineering, Virtualisation Team

M:       +44 (0)7977 267231
GPG ID:  D33C3490
GPG FPR: 3733 612D 2D05 5458 8A8A 1600 3441 EA19 D33C 3490

[-- Attachment #2: 0001-Documentation-Add-documentation-for-chardev.patch --]
[-- Type: text/plain, Size: 9140 bytes --]

>From 1ffa1f65fce29963235bd24e44582bcccc5c5106 Mon Sep 17 00:00:00 2001
From: Matthew Booth <mbooth@redhat.com>
Date: Thu, 29 Oct 2009 15:05:09 +0000
Subject: [PATCH] Documentation: Add documentation for -chardev

Adds documentation for all -chardev backends.
---
 qemu-options.hx |  234 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 230 insertions(+), 4 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index d78b738..7922191 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1085,8 +1085,237 @@ is activated if no @option{-net} options are provided.
 @end table
 ETEXI
 
+DEFHEADING()
+
+DEFHEADING(Character device options:)
+
+DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
+    "-chardev null,id=id\n"
+    "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
+    "         [,server][,nowait][,telnet] (tcp)\n"
+    "-chardev socket,id=id,path=path[,server][,nowait][,telnet] (unix)\n"
+    "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
+    "         [,localport=localport][,ipv4][,ipv6]\n"
+    "-chardev msmouse,id=id\n"
+    "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
+    "-chardev file,id=id,path=path\n"
+    "-chardev pipe,id=id,path=path\n"
+#ifdef _WIN32
+    "-chardev console,id=id\n"
+    "-chardev serial,id=id,path=path\n"
+#else
+    "-chardev pty,id=id\n"
+    "-chardev stdio,id=id\n"
+#endif
+#ifdef CONFIG_BRLAPI
+    "-chardev braille,id=id\n"
+#endif
+#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
+        || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
+    "-chardev tty,id=id,path=path\n"
+#endif
+#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
+    "-chardev parport,id=id,path=path\n"
+#endif
+)
+
+STEXI
+
+The general form of a character device option is:
+@table @option
+
+@item -chardev @var{backend} ,id=@var{id} [,@var{options}]
+
+Backend is one of:
+@option{null},
+@option{socket},
+@option{udp},
+@option{msmouse},
+@option{vc},
+@option{file},
+@option{pipe},
+@option{console},
+@option{serial},
+@option{pty},
+@option{stdio},
+@option{braille},
+@option{tty},
+@option{parport}.
+The specific backend will determine the applicable options.
+
+All devices must have an id, which can be any string up to 127 characters long.
+It is used to uniquely identify this device in other command line directives.
+
+Options to each backend are described below.
+
+@item -chardev null ,id=@var{id}
+A void device. This device will not emit any data, and will drop any data it
+receives. The null backend does not take any options.
+
+@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
+
+Create a two-way stream socket, which can be either a TCP or a unix socket. A
+unix socket will be created if @option{path} is specified. Behaviour is
+undefined if TCP options are specified for a unix socket.
+
+@option{server} specifies that the socket shall be a listening socket.
+
+@option{nowait} specifies that QEMU should not block waiting for a client to
+connect to a listening socket.
+
+@option{telnet} specifies that traffic on the socket should interpret telnet
+escape sequences.
+
+TCP and unix socket options are given below:
+
+@table @option
+
+@item TCP options: port=@var{host} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
+
+@option{host} for a listening socket specifies the local address to be bound.
+For a connecting socket species the remote host to connect to. @option{host} is
+optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
+
+@option{port} for a listening socket specifies the local port to be bound. For a
+connecting socket specifies the port on the remote host to connect to.
+@option{port} can be given as either a port number or a service name.
+@option{port} is required.
+
+@option{to} is only relevant to listening sockets. If it is specified, and
+@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
+to and including @option{to} until it succeeds. @option{to} must be specified
+as a port number.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the socket may use either protocol.
+
+@option{nodelay} disables the Nagle algorithm.
+
+@item unix options: path=@var{path}
+
+@option{path} specifies the local path of the unix socket. @option{path} is
+required.
+
+@end table
+
+@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
+
+Sends all traffic from the guest to a remote host over UDP.
+
+@option{host} specifies the remote host to connect to. If not specified it
+defaults to @code{localhost}.
+
+@option{port} specifies the port on the remote host to connect to. @option{port}
+is required.
+
+@option{localaddr} specifies the local address to bind to. If not specified it
+defaults to @code{0.0.0.0}.
+
+@option{localport} specifies the local port to bind to. If not specified any
+available local port will be used.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the device may use either protocol.
+
+@item -chardev msmouse ,id=@var{id}
+
+Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
+take any options.
+
+@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
+
+Connect to a QEMU text console. @option{vc} may optionally be given a specific
+size.
+
+@option{width} and @option{height} specify the width and height respectively of
+the console, in pixels.
+
+@option{cols} and @option{rows} specify that the console be sized to fit a text
+console with the given dimensions.
+
+@item -chardev file ,id=@var{id} ,path=@var{path}
+
+Log all traffic received from the guest to a file.
+
+@option{path} specifies the path of the file to be opened. This file will be
+created if it does not already exist, and overwritten if it does. @option{path}
+is required.
+
+@item -chardev pipe ,id=@var{id} ,path=@var{path}
+
+Create a two-way connection to the guest. The behaviour differs slightly between
+Windows hosts and other hosts:
+
+On Windows, a single duplex pipe will be created at
+@file{\\.pipe\@option{path}}.
+
+On other hosts, 2 pipes will be created called @file{@option{path}.in} and
+@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
+received by the guest. Data written by the guest can be read from
+@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
+be present.
+
+@option{path} forms part of the pipe path as described above. @option{path} is
+required.
+
+@item -chardev console ,id=@var{id}
+
+Send traffic from the guest to QEMU's standard output. @option{console} does not
+take any options.
+
+@option{console} is only available on Windows hosts.
+
+@item -chardev serial ,id=@var{id} ,path=@option{path}
+
+Send traffic from the guest to a serial device on the host.
+
+@option{serial} is
+only available on Windows hosts.
+
+@option{path} specifies the name of the serial device to open.
+
+@item -chardev pty ,id=@var{id}
+
+Create a new pseudo-terminal on the host and connect to it. @option{pty} does
+not take any options.
+
+@option{pty} is not available on Windows hosts.
+
+@item -chardev stdio ,id=@var{id}
+Connect to standard input and standard output of the qemu process.
+@option{stdio} does not take any options. @option{stdio} is not available on
+Windows hosts.
+
+@item -chardev braille ,id=@var{id}
+
+Connect to a local BrlAPI server. @option{braille} does not take any options.
+
+@item -chardev tty ,id=@var{id} ,path=@var{path}
+
+Connect to a local tty device.
+
+@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
+DragonFlyBSD hosts.
+
+@option{path} specifies the path to the tty. @option{path} is required.
+
+@item -chardev parport ,id=@var{id} ,path=@var{path}
+
+@option{parport} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
+
+Connect to a local parallel port.
+
+@option{path} specifies the path to the parallel port device. @option{path} is
+required.
+
+@end table
+ETEXI
+
+DEFHEADING()
+
+DEFHEADING(Bluetooth(R) options:)
+
 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
-    "\n" \
     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
     "-bt hci,host[:id]\n" \
     "                use host's HCI with the given name\n" \
@@ -1097,7 +1326,6 @@ DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
     "-bt device:dev[,vlan=n]\n" \
     "                emulate a bluetooth device 'dev' in scatternet 'n'\n")
 STEXI
-Bluetooth(R) options:
 @table @option
 
 @item -bt hci[...]
@@ -1206,8 +1434,6 @@ STEXI
 @table @option
 ETEXI
 
-DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, \
-    "-chardev spec   create unconnected chardev\n")
 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
     "-serial dev     redirect the serial port to char device 'dev'\n")
 STEXI
-- 
1.6.2.5

[Qemu-devel] Re: [PATCH] Documentation: Add documentation for -chardev

[Gerd Hoffmann]

   Hi,

> New patch attached.

Looks good now.

thanks,
   Gerd

[Qemu-devel] Documentation: Add documentation for -chardev

[Matthew Booth]

Matt

[Qemu-devel] [PATCH] Documentation: Add documentation for -chardev

[Matthew Booth]

Adds documentation for all -chardev backends.

Signed-off-by: Matthew Booth <mbooth@redhat.com>
---
 qemu-options.hx |  234 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 230 insertions(+), 4 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index d78b738..7922191 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1085,8 +1085,237 @@ is activated if no @option{-net} options are provided.
 @end table
 ETEXI
 
+DEFHEADING()
+
+DEFHEADING(Character device options:)
+
+DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
+    "-chardev null,id=id\n"
+    "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
+    "         [,server][,nowait][,telnet] (tcp)\n"
+    "-chardev socket,id=id,path=path[,server][,nowait][,telnet] (unix)\n"
+    "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
+    "         [,localport=localport][,ipv4][,ipv6]\n"
+    "-chardev msmouse,id=id\n"
+    "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
+    "-chardev file,id=id,path=path\n"
+    "-chardev pipe,id=id,path=path\n"
+#ifdef _WIN32
+    "-chardev console,id=id\n"
+    "-chardev serial,id=id,path=path\n"
+#else
+    "-chardev pty,id=id\n"
+    "-chardev stdio,id=id\n"
+#endif
+#ifdef CONFIG_BRLAPI
+    "-chardev braille,id=id\n"
+#endif
+#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
+        || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
+    "-chardev tty,id=id,path=path\n"
+#endif
+#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
+    "-chardev parport,id=id,path=path\n"
+#endif
+)
+
+STEXI
+
+The general form of a character device option is:
+@table @option
+
+@item -chardev @var{backend} ,id=@var{id} [,@var{options}]
+
+Backend is one of:
+@option{null},
+@option{socket},
+@option{udp},
+@option{msmouse},
+@option{vc},
+@option{file},
+@option{pipe},
+@option{console},
+@option{serial},
+@option{pty},
+@option{stdio},
+@option{braille},
+@option{tty},
+@option{parport}.
+The specific backend will determine the applicable options.
+
+All devices must have an id, which can be any string up to 127 characters long.
+It is used to uniquely identify this device in other command line directives.
+
+Options to each backend are described below.
+
+@item -chardev null ,id=@var{id}
+A void device. This device will not emit any data, and will drop any data it
+receives. The null backend does not take any options.
+
+@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
+
+Create a two-way stream socket, which can be either a TCP or a unix socket. A
+unix socket will be created if @option{path} is specified. Behaviour is
+undefined if TCP options are specified for a unix socket.
+
+@option{server} specifies that the socket shall be a listening socket.
+
+@option{nowait} specifies that QEMU should not block waiting for a client to
+connect to a listening socket.
+
+@option{telnet} specifies that traffic on the socket should interpret telnet
+escape sequences.
+
+TCP and unix socket options are given below:
+
+@table @option
+
+@item TCP options: port=@var{host} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
+
+@option{host} for a listening socket specifies the local address to be bound.
+For a connecting socket species the remote host to connect to. @option{host} is
+optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
+
+@option{port} for a listening socket specifies the local port to be bound. For a
+connecting socket specifies the port on the remote host to connect to.
+@option{port} can be given as either a port number or a service name.
+@option{port} is required.
+
+@option{to} is only relevant to listening sockets. If it is specified, and
+@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
+to and including @option{to} until it succeeds. @option{to} must be specified
+as a port number.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the socket may use either protocol.
+
+@option{nodelay} disables the Nagle algorithm.
+
+@item unix options: path=@var{path}
+
+@option{path} specifies the local path of the unix socket. @option{path} is
+required.
+
+@end table
+
+@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
+
+Sends all traffic from the guest to a remote host over UDP.
+
+@option{host} specifies the remote host to connect to. If not specified it
+defaults to @code{localhost}.
+
+@option{port} specifies the port on the remote host to connect to. @option{port}
+is required.
+
+@option{localaddr} specifies the local address to bind to. If not specified it
+defaults to @code{0.0.0.0}.
+
+@option{localport} specifies the local port to bind to. If not specified any
+available local port will be used.
+
+@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
+If neither is specified the device may use either protocol.
+
+@item -chardev msmouse ,id=@var{id}
+
+Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
+take any options.
+
+@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
+
+Connect to a QEMU text console. @option{vc} may optionally be given a specific
+size.
+
+@option{width} and @option{height} specify the width and height respectively of
+the console, in pixels.
+
+@option{cols} and @option{rows} specify that the console be sized to fit a text
+console with the given dimensions.
+
+@item -chardev file ,id=@var{id} ,path=@var{path}
+
+Log all traffic received from the guest to a file.
+
+@option{path} specifies the path of the file to be opened. This file will be
+created if it does not already exist, and overwritten if it does. @option{path}
+is required.
+
+@item -chardev pipe ,id=@var{id} ,path=@var{path}
+
+Create a two-way connection to the guest. The behaviour differs slightly between
+Windows hosts and other hosts:
+
+On Windows, a single duplex pipe will be created at
+@file{\\.pipe\@option{path}}.
+
+On other hosts, 2 pipes will be created called @file{@option{path}.in} and
+@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
+received by the guest. Data written by the guest can be read from
+@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
+be present.
+
+@option{path} forms part of the pipe path as described above. @option{path} is
+required.
+
+@item -chardev console ,id=@var{id}
+
+Send traffic from the guest to QEMU's standard output. @option{console} does not
+take any options.
+
+@option{console} is only available on Windows hosts.
+
+@item -chardev serial ,id=@var{id} ,path=@option{path}
+
+Send traffic from the guest to a serial device on the host.
+
+@option{serial} is
+only available on Windows hosts.
+
+@option{path} specifies the name of the serial device to open.
+
+@item -chardev pty ,id=@var{id}
+
+Create a new pseudo-terminal on the host and connect to it. @option{pty} does
+not take any options.
+
+@option{pty} is not available on Windows hosts.
+
+@item -chardev stdio ,id=@var{id}
+Connect to standard input and standard output of the qemu process.
+@option{stdio} does not take any options. @option{stdio} is not available on
+Windows hosts.
+
+@item -chardev braille ,id=@var{id}
+
+Connect to a local BrlAPI server. @option{braille} does not take any options.
+
+@item -chardev tty ,id=@var{id} ,path=@var{path}
+
+Connect to a local tty device.
+
+@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
+DragonFlyBSD hosts.
+
+@option{path} specifies the path to the tty. @option{path} is required.
+
+@item -chardev parport ,id=@var{id} ,path=@var{path}
+
+@option{parport} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
+
+Connect to a local parallel port.
+
+@option{path} specifies the path to the parallel port device. @option{path} is
+required.
+
+@end table
+ETEXI
+
+DEFHEADING()
+
+DEFHEADING(Bluetooth(R) options:)
+
 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
-    "\n" \
     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
     "-bt hci,host[:id]\n" \
     "                use host's HCI with the given name\n" \
@@ -1097,7 +1326,6 @@ DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
     "-bt device:dev[,vlan=n]\n" \
     "                emulate a bluetooth device 'dev' in scatternet 'n'\n")
 STEXI
-Bluetooth(R) options:
 @table @option
 
 @item -bt hci[...]
@@ -1206,8 +1434,6 @@ STEXI
 @table @option
 ETEXI
 
-DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, \
-    "-chardev spec   create unconnected chardev\n")
 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
     "-serial dev     redirect the serial port to char device 'dev'\n")
 STEXI
-- 
1.6.2.5