From patchwork Fri Oct 30 10:56:10 2009 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthew Booth X-Patchwork-Id: 37268 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id CD2F8B7C33 for ; Fri, 30 Oct 2009 21:57:13 +1100 (EST) Received: from localhost ([127.0.0.1]:40129 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1N3pAL-000205-Ts for incoming@patchwork.ozlabs.org; Fri, 30 Oct 2009 06:57:09 -0400 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1N3p9Z-0001zD-S2 for qemu-devel@nongnu.org; Fri, 30 Oct 2009 06:56:21 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1N3p9T-0001wq-LP for qemu-devel@nongnu.org; Fri, 30 Oct 2009 06:56:19 -0400 Received: from [199.232.76.173] (port=37058 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1N3p9T-0001wn-5z for qemu-devel@nongnu.org; Fri, 30 Oct 2009 06:56:15 -0400 Received: from mx1.redhat.com ([209.132.183.28]:28447) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1N3p9S-0007ZW-Gx for qemu-devel@nongnu.org; Fri, 30 Oct 2009 06:56:14 -0400 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id n9UAuDZ0016088 for ; Fri, 30 Oct 2009 06:56:13 -0400 Received: from mbooth.laptop (vpn1-6-18.ams2.redhat.com [10.36.6.18]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id n9UAuBRH014823; Fri, 30 Oct 2009 06:56:12 -0400 Message-ID: <4AEAC64A.3050103@redhat.com> Date: Fri, 30 Oct 2009 10:56:10 +0000 From: Matthew Booth Organization: Red Hat User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.4pre) Gecko/20091014 Fedora/3.0-2.8.b4.fc11 Lightning/1.0pre Thunderbird/3.0b4 MIME-Version: 1.0 To: Gerd Hoffmann References: <1256832211-14532-2-git-send-email-mbooth@redhat.com> <1256835400-16258-1-git-send-email-mbooth@redhat.com> <1256835400-16258-2-git-send-email-mbooth@redhat.com> <4AEAAF35.8080808@redhat.com> In-Reply-To: <4AEAAF35.8080808@redhat.com> X-Scanned-By: MIMEDefang 2.67 on 10.5.11.12 X-detected-operating-system: by monty-python.gnu.org: Genre and OS details not recognized. Cc: qemu-devel@nongnu.org Subject: [Qemu-devel] Re: [PATCH] Documentation: Add documentation for -chardev X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org 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 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