12:58 a.m.
This change refactors the existing character device documentation to make it
explicit which directives configure the guest interface, and which configure the
host interface.
* docs/formatdomain.html.in: Do it.
---
docs/formatdomain.html.in | 117 ++++++++++++++++++++++++++++++++++-----------
1 files changed, 88 insertions(+), 29 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 72bd7b9..be35ad0 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -789,28 +789,87 @@ qemu-kvm -net nic,model=? /dev/null
</devices>
</domain></pre>
+ <p>
+ In each of these directives, the top-level element name (parallel, serial,
+ console, channel) describes how the device is presented to the guest. The
+ guest interface is configured by the <code>target</code> element.
+ </p>
- <dl>
- <dt><code>parallel</code></dt>
- <dd>Represents a parallel port</dd>
- <dt><code>serial</code></dt>
- <dd>Represents a serial port</dd>
- <dt><code>console</code></dt>
- <dd>Represents the primary console. This can be the paravirtualized
- console with Xen guests, or duplicates the primary serial port
- for fully virtualized guests without a paravirtualized console.</dd>
- <dt><code>source</code></dt>
- <dd>The attributes available for the <code>source</code> element
- vary according to the <code>type</code> attribute on the parent
- tag. Allowed variations will be described below</dd>
- <dt><code>target</code></dt>
- <dd>The port number of the character device is specified via the
- <code>port</code> attribute, numbered starting from 1. There is
- usually only one console device, and 0, 1 or 2 serial devices
- or parallel devices.
- </dl>
+ <p>
+ The interface presented to the host is given in the <code>type</code>
+ attribute of the top-level element. The host interface is
+ configured by the <code>source</code> element.
+ </p>
+
+ <h5><a name="elementsCharGuestInterface">Guest
interface</a></h5>
+
+ <p>
+ A character device presents itself to the guest as one of the following
+ types.
+ </p>
+
+ <h6><a name="elementCharParallel">Parallel
port</a></h6>
+
+ <pre>
+ ...
+ <parallel type='pty'>
+ <source path='/dev/pts/2'/>
+ <target port='0'/>
+ </parallel>
+ ...</pre>
+
+ <p>
+ <code>target</code> can have a <code>port</code> attribute,
which
+ specifies the port number. Ports are numbered starting from 1. There are
+ usually 0, 1 or 2 parallel ports.
+ </p>
+
+ <h6><a name="elementCharSerial">Serial
port</a></h6>
+
+ <pre>
+ ...
+ <serial type='pty'>
+ <source path='/dev/pts/3'/>
+ <target port='0'/>
+ </serial>
+ ...</pre>
+
+ <p>
+ <code>target</code> can have a <code>port</code> attribute,
which
+ specifies the port number. Ports are numbered starting from 1. There are
+ usually 0, 1 or 2 serial ports.
+ </p>
+
+ <h6><a name="elementCharConsole">Console</a></h6>
+
+ <p>
+ This represents the primary console. This can be the paravirtualized
+ console with Xen guests, or duplicates the primary serial port for fully
+ virtualized guests without a paravirtualized console.
+ </p>
+
+ <pre>
+ ...
+ <console type='pty'>
+ <source path='/dev/pts/4'/>
+ <target port='0'/>
+ </console>
+ ...</pre>
+
+ <p>
+ If the console is presented as a serial port, the <code>target</code>
+ element has the same attributes as for a serial port. There is usually
+ only 1 console.
+ </p>
+
+ <h5><a name="elementsCharHostInterface">Host
interface</a></h5>
+
+ <p>
+ A character device presents itself to the host as one of the following
+ types.
+ </p>
- <h5><a name="elementsCharSTDIO">Domain
logfile</a></h5>
+ <h6><a name="elementsCharSTDIO">Domain
logfile</a></h6>
<p>
This disables all input on the character device, and sends output
@@ -825,7 +884,7 @@ qemu-kvm -net nic,model=? /dev/null
...</pre>
- <h5><a name="elementsCharFle">Device
logfile</a></h5>
+ <h6><a name="elementsCharFle">Device
logfile</a></h6>
<p>
A file is opened and all data sent to the character
@@ -840,7 +899,7 @@ qemu-kvm -net nic,model=? /dev/null
</serial>
...</pre>
- <h5><a name="elementsCharVC">Virtual
console</a></h5>
+ <h6><a name="elementsCharVC">Virtual
console</a></h6>
<p>
Connects the character device to the graphical framebuffer in
@@ -855,7 +914,7 @@ qemu-kvm -net nic,model=? /dev/null
</serial>
...</pre>
- <h5><a name="elementsCharNull">Null
device</a></h5>
+ <h6><a name="elementsCharNull">Null
device</a></h6>
<p>
Connects the character device to the void. No data is ever
@@ -869,7 +928,7 @@ qemu-kvm -net nic,model=? /dev/null
</serial>
...</pre>
- <h5><a name="elementsCharPTY">Pseudo TTY</a></h5>
+ <h6><a name="elementsCharPTY">Pseudo TTY</a></h6>
<p>
A Pseudo TTY is allocated using /dev/ptmx. A suitable client
@@ -892,7 +951,7 @@ qemu-kvm -net nic,model=? /dev/null
with existing syntax for <console> tags.
</p>
- <h5><a name="elementsCharHost">Host device
proxy</a></h5>
+ <h6><a name="elementsCharHost">Host device
proxy</a></h6>
<p>
The character device is passed through to the underlying
@@ -910,7 +969,7 @@ qemu-kvm -net nic,model=? /dev/null
</serial>
...</pre>
- <h5><a name="elementsCharPipe">Named pipe</a></h5>
+ <h6><a name="elementsCharPipe">Named pipe</a></h6>
<p>
The character device writes output to a named pipe. See pipe(7) for
@@ -925,7 +984,7 @@ qemu-kvm -net nic,model=? /dev/null
</serial>
...</pre>
- <h5><a name="elementsCharTCP">TCP
client/server</a></h5>
+ <h6><a name="elementsCharTCP">TCP
client/server</a></h6>
<p>
The character device acts as a TCP client connecting to a
@@ -973,7 +1032,7 @@ qemu-kvm -net nic,model=? /dev/null
</serial>
...</pre>
- <h5><a name="elementsCharUDP">UDP network
console</a></h5>
+ <h6><a name="elementsCharUDP">UDP network
console</a></h6>
<p>
The character device acts as a UDP netconsole service,
@@ -989,7 +1048,7 @@ qemu-kvm -net nic,model=? /dev/null
</serial>
...</pre>
- <h5><a name="elementsCharUNIX">UNIX domain socket
client/server</a></h5>
+ <h6><a name="elementsCharUNIX">UNIX domain socket
client/server</a></h6>
<p>
The character device acts as a UNIX domain socket server,
--
1.6.2.5