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} [,i...@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 [,i...@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: po...@var{host} [,ho...@var{host}] [,t...@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: pa...@var{path}
+
+...@option{path} specifies the local path of the unix socket. @option{path} is
+required.
+
+...@end table
+
+...@item -chardev udp [,i...@var{id}] [,ho...@var{host}] ,po...@var{port}
[,localad...@var{localaddr}] [,localpo...@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 [,i...@var{id}]
+
+Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
+take any options.
+
+...@item -chardev vc [,i...@var{id}]
+
+Connect to a QEMU text console. @option{vc} does not take any options.
+
+...@item -chardev file [,i...@var{id}] ,pa...@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 [,i...@var{id}] ,pa...@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 @fi...@option{path}.in} and
+...@file{@option{path}.out}. Data written to @fi...@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 [,i...@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 [,i...@var{id}] ,pa...@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 [,i...@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 [,i...@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 [,i...@var{id}]
+
+Connect to a local BrlAPI server. @option{braille} does not take any options.
+
+...@item -chardev tty [,i...@var{id}] ,pa...@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 [,i...@var{id}] ,pa...@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
