>From 1ffa1f65fce29963235bd24e44582bcccc5c5106 Mon Sep 17 00:00:00 2001 From: Matthew Booth 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: address@hidden @option + address@hidden -chardev @var{backend} ,address@hidden [,@var{options}] + +Backend is one of: address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden, address@hidden +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. + address@hidden -chardev null ,address@hidden +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. + address@hidden -chardev socket ,address@hidden address@hidden 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. + address@hidden specifies that the socket shall be a listening socket. + address@hidden specifies that QEMU should not block waiting for a client to +connect to a listening socket. + address@hidden specifies that traffic on the socket should interpret telnet +escape sequences. + +TCP and unix socket options are given below: + address@hidden @option + address@hidden TCP options: address@hidden [,address@hidden [,address@hidden [,ipv4] [,ipv6] [,nodelay] + address@hidden 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}. + address@hidden 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. address@hidden can be given as either a port number or a service name. address@hidden is required. + address@hidden is only relevant to listening sockets. If it is specified, and address@hidden 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. + address@hidden and @option{ipv6} specify that either IPv4 or IPv6 must be used. +If neither is specified the socket may use either protocol. + address@hidden disables the Nagle algorithm. + address@hidden unix options: address@hidden + address@hidden specifies the local path of the unix socket. @option{path} is +required. + address@hidden table + address@hidden -chardev udp ,address@hidden [,address@hidden ,address@hidden [,address@hidden [,address@hidden [,ipv4] [,ipv6] + +Sends all traffic from the guest to a remote host over UDP. + address@hidden specifies the remote host to connect to. If not specified it +defaults to @code{localhost}. + address@hidden specifies the port on the remote host to connect to. @option{port} +is required. + address@hidden specifies the local address to bind to. If not specified it +defaults to @code{0.0.0.0}. + address@hidden specifies the local port to bind to. If not specified any +available local port will be used. + address@hidden and @option{ipv6} specify that either IPv4 or IPv6 must be used. +If neither is specified the device may use either protocol. + address@hidden -chardev msmouse ,address@hidden + +Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not +take any options. + address@hidden -chardev vc ,address@hidden [[,address@hidden [,address@hidden [[,address@hidden [,address@hidden + +Connect to a QEMU text console. @option{vc} may optionally be given a specific +size. + address@hidden and @option{height} specify the width and height respectively of +the console, in pixels. + address@hidden and @option{rows} specify that the console be sized to fit a text +console with the given dimensions. + address@hidden -chardev file ,address@hidden ,address@hidden + +Log all traffic received from the guest to a file. + address@hidden 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. + address@hidden -chardev pipe ,address@hidden ,address@hidden + +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 address@hidden@option{path}}. + +On other hosts, 2 pipes will be created called @address@hidden and address@hidden@option{path}.out}. Data written to @address@hidden will be +received by the guest. Data written by the guest can be read from address@hidden@option{path}.out}. QEMU will not create these fifos, and requires them to +be present. + address@hidden forms part of the pipe path as described above. @option{path} is +required. + address@hidden -chardev console ,address@hidden + +Send traffic from the guest to QEMU's standard output. @option{console} does not +take any options. + address@hidden is only available on Windows hosts. + address@hidden -chardev serial ,address@hidden ,address@hidden + +Send traffic from the guest to a serial device on the host. + address@hidden is +only available on Windows hosts. + address@hidden specifies the name of the serial device to open. + address@hidden -chardev pty ,address@hidden + +Create a new pseudo-terminal on the host and connect to it. @option{pty} does +not take any options. + address@hidden is not available on Windows hosts. + address@hidden -chardev stdio ,address@hidden +Connect to standard input and standard output of the qemu process. address@hidden does not take any options. @option{stdio} is not available on +Windows hosts. + address@hidden -chardev braille ,address@hidden + +Connect to a local BrlAPI server. @option{braille} does not take any options. + address@hidden -chardev tty ,address@hidden ,address@hidden + +Connect to a local tty device. + address@hidden is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and +DragonFlyBSD hosts. + address@hidden specifies the path to the tty. @option{path} is required. + address@hidden -chardev parport ,address@hidden ,address@hidden + address@hidden is only available on Linux, FreeBSD and DragonFlyBSD hosts. + +Connect to a local parallel port. + address@hidden specifies the path to the parallel port device. @option{path} is +required. + address@hidden 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