You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Linux-Architecture-Reference/Virtualization/ch_virtual_tty.xml

1042 lines
38 KiB
XML

<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdoclet.50569375_64200">
<title>A Protocol for a Virtual TTY Interface</title>
<section>
<title>Overview</title>
<para>This chapter defines a protocol to support partition use of a
physical serial port using a virtual TTY (VTY) interface. A protocol is
required to send control and status information of the physical device
using a data only transport.</para>
<para>Specifically, this protocol is used to allow the Virtual Terminal
(VTERM) option, as defined in
<xref linkend="dbdoclet.50569352_15379" />, as the interface to communicate
with a physical serial port which is under control of the platform instead
of the OS.</para>
<para>This chapter describes a connection between the platform, which has
physical control of the serial port and is an endpoint of the VTERM
interface, and a partition, which is the other endpoint of the VTERM
interface. The protocol described here provides a means to communicate both
data and control information over this data-only interface.</para>
</section>
<section>
<title>Protocol Definition</title>
<section>
<title>Packet Formation</title>
<para>All information is sent in packets. There are four types of packets
supported for version 0, data packets, control packets, query packets and
query response packets. A packet consists of a one byte header, which
defines the type of packet, followed by a one byte length field, followed
by a two byte sequence number, followed by the packet payload, which
depends on the type of packet. This means that the minimum packet size is
5 bytes, in the case of a one-byte data packet.</para>
<para>The one-byte length field for the packet is the length of the
entire packet, including the header byte and the length field
itself.</para>
<para>On the partition side the H_GET_TERM_CHAR and H_PUT_TERM_CHAR
hypervisor calls are used to read and write data. These HCALLS read and
write up to 16 bytes of data at once. There is no relationship between
the data in a particular HCALL and packet boundaries. A single packet can
span multiple HCALLS, and a single HCALL can contain data from more than
one packet.</para>
<para>For version 0, the following packet headers are defined:</para>
<section>
<title>Data Packet</title>
<programlisting><![CDATA[#define VS_DATA_PACKET_HEADER 0xFF]]></programlisting>
<para>This packet type is used to send data.</para>
<para>The data packet is defined in
<xref linkend="dbdoclet.50569375_39781" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_39781">
<title>VTERM Data Packet</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Packet Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Member Size (Bytes)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Packet Header (0xFF)</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Total size of packet in bytes, including this
header</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Sequence Number (see description below)</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>variable</para>
</entry>
<entry>
<para>Data</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Control Packet</title>
<programlisting><![CDATA[#define VS_CONTROL_PACKET_HEADER 0xFE]]></programlisting>
<para>This packet type is used to send commands that control the
operation of software or hardware on the other side of the link, and to
send notification of status changes on the other side.</para>
<para>The control packet is defined in
<xref linkend="dbdoclet.50569375_94407" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_94407">
<title>VTERM Control Packet</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Packet Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Member Size (Bytes)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Packet Header (0xFE)</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Total size of packet in bytes, including this
header</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Sequence Number (see description below)</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Control verb (see description below)</para>
</entry>
</row>
<row>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>optional and variable</para>
</entry>
<entry>
<para>Depending on verb, further data</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The following control verbs are supported.</para>
<section>
<title>VSV_SET_MODEM_CTL Verb (0x01)</title>
<para>
<emphasis role="bold">Protocol Version:</emphasis> 0x00</para>
<para>
<emphasis role="bold">Note:</emphasis> One-way. This verb is only sent by the
partition to the platform.</para>
<para>
<emphasis role="bold">Data Member Definition:</emphasis> The data member for this verb
consists of 8 bytes, as defined in
<xref linkend="dbdoclet.50569375_31856" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_31856">
<title>VSV_SET_MODEM_CTL Verb Data Member</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Packet Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Member Size (Bytes)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>VS_MODEM_CTL word (defined below)</para>
</entry>
</row>
<row>
<entry>
<para>0xA</para>
</entry>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>VS_MODEM_CTL mask, defining which bits in the control
word above are to be updated.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>VS_MODEM_CTL is a 4 byte bit-mask. The following bits are defined.
Note that each bit position has an associated protocol version. Note that
some bits can bet set (noted as R/W in the table), others only can be
read (noted as R/O in the table). This verb will set only bits marked
R/W.</para>
<para>The update of the serial port hardware driven by this command must
be serialized with data packets.</para>
<para>In the data portion of the packet, the first word defines the bit
values to be set; the second word is a mask defining which bits are to be
updated. See
<xref linkend="dbdoclet.50569375_21059" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_21059">
<title>VS_MODEM_CTL Bit Definition</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="5">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="20*" align="center" />
<colspec colname="c5" colwidth="20*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Bit Position</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Protocol Version Supported</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">R/O, R/W</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>0x0000001</para>
</entry>
<entry>
<para>0x00</para>
</entry>
<entry>
<para>R/W</para>
</entry>
<entry>
<para>TSDTR</para>
</entry>
<entry>
<para>Data Terminal Ready</para>
</entry>
</row>
<row>
<entry>
<para>0x0000020</para>
</entry>
<entry>
<para>0x00</para>
</entry>
<entry>
<para>R/O</para>
</entry>
<entry>
<para>TSCD</para>
</entry>
<entry>
<para>Carrier Detect</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>VSV_MODEM_CTL_UPDATE Verb (0x02)</title>
<para>
<emphasis role="bold">Protocol Version:</emphasis> 0x00</para>
<para>
<emphasis role="bold">Note:</emphasis> One-way. This verb is only sent by the platform
to the partition.</para>
<para>
<emphasis role="bold">Data Member Definition:</emphasis> The data member for this verb
consists of 4 bytes, as defined in
<xref linkend="dbdoclet.50569375_44278" /></para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_44278">
<title>VSV_MODEM_CTL_UPDATE Verb Data Member</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Packet Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Member Size (Bytes)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>VS_MODEM_CTL word (defined above)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This packet is sent by platform to the partition to inform the
partition of a change in status of certain bits in the VS_MODEM_CTL word.
The bits which cause this command to be sent when they transition are
defined in
<xref linkend="dbdoclet.50569375_17217" />. This command should be
serialized with data packets. The protocol version in
<xref linkend="dbdoclet.50569375_17217" /> defines the first (lowest)
version of the protocol in which a transition of this bit should cause
the command to be sent.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_17217">
<title>VS_MODEM_CTL Word Bits</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Bit Name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Protocol Version Supported</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>TSCD</para>
</entry>
<entry>
<para>0x00</para>
</entry>
<entry>
<para>A transition of carrier detect must cause this packet to
be sent.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>VSV_RENEGOTIATE_CONNECTION Verb (0x03)</title>
<para>
<emphasis role="bold">Protocol Version:</emphasis> 0x00</para>
<para>
<emphasis role="bold">Data Member Definition:</emphasis> No data member for this
verb.</para>
<para>This verb forces the protocol into &#8220;closed&#8221; state; see
the Connection Negotiation section below for the definition and meaning
of this state.</para>
<para>In normal operation it is expected that this command will be send
from the partition to the platform. However, if the platform is aware
that it will be unable to continue for some reason for a finite period of
time, it can send this command to the partition.</para>
<para>The platform may send this command even if the protocol is not in
an open state; this is to allow the platform to unconditionally close the
platform during an error recovery processor.</para>
<para>When the partition transitions control of the VTY between
independent entities, such as when it is given from OF control the to the
OS, the protocol should be closed with this command by the component that
is relinquishing it and reopened by the receiving component.</para>
</section>
</section>
<section>
<title>Query Packet</title>
<programlisting><![CDATA[#define VS_QUERY_PACKET_HEADER 0xFD]]></programlisting>
<para>This packet is used to send queries to the other side of the link.
The other side responds by sending a query response packet, defined
below. There is in some case implied control of the state of the other
side of the link, as a series of queries and responses are used to
initialize (or re-initialize) the protocol.</para>
<para>The query packet is defined in
<xref linkend="dbdoclet.50569375_12777" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_12777">
<title>VTERM Query Packet</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Packet Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Member Size (Bytes)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Packet Header (0xFD)</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Total size of packet in bytes, including this header
(0x6)</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Sequence Number (see description below)</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Query verb (see description below)</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The following query verbs are supported:</para>
<section>
<title>VSV_SEND_VERSION_NUMBER Verb (0x01)</title>
<para>
<emphasis role="bold">Protocol Version:</emphasis> 0x00</para>
<para>
<emphasis role="bold">Response:</emphasis> The query response data member will contain
the one-byte version number of the highest version of the protocol
supported by the driver.</para>
</section>
<section>
<title>VSV_SEND_MODEM_CTL_STATUS Verb (0x02)</title>
<para>
<emphasis role="bold">Protocol Version:</emphasis> 0x00</para>
<para>
<emphasis role="bold">Response:</emphasis> The query response data member will contain
the four-byte VS_MODEM_CTL word defined above in the VSV_SET_MODEM_CTL
verb.</para>
<para>
<emphasis role="bold">Note:</emphasis> One-way. This verb is only sent by the
partition to the platform.</para>
</section>
</section>
<section>
<title>Query Response Packet</title>
<programlisting><![CDATA[#define VS_QUERY_RESPONSE_PACKET_HEADER 0xFC]]></programlisting>
<para>This packet is used to reply to query packets sent from the other
side of the link, and are sent only in response to query packets.</para>
<para>The query response packet is defined in
<xref linkend="dbdoclet.50569375_51311" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_51311">
<title>VTERM Query Response Packet</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="25*" align="center" />
<colspec colname="c2" colwidth="25*" align="center" />
<colspec colname="c3" colwidth="50*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Packet Offset</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Member Size (Bytes)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0x0</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Packet Header (0xFC)</para>
</entry>
</row>
<row>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>Total size of packet in bytes, including this
header</para>
</entry>
</row>
<row>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Sequence Number (see description below)</para>
</entry>
</row>
<row>
<entry>
<para>0x4</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Query verb -- matches the query verb for which this is a
response</para>
</entry>
</row>
<row>
<entry>
<para>0x6</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>Query Sequence Number -- the sequence number of the query
packet for which this is a response</para>
</entry>
</row>
<row>
<entry>
<para>0x8</para>
</entry>
<entry>
<para>variable</para>
</entry>
<entry>
<para>Verb-specific response data</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section>
<title>Verb Formation</title>
<para>A verb, either for a command or query packet, consists of two
bytes. The first byte is a version of the protocol associated with the
verb, and the second byte is the verb itself. This allows the flexibility
to redefine or add function to verbs in the future. More importantly, it
allows partners at either end of the protocol to find a &#8220;least
common denominator&#8221; at which they can work.</para>
<para>The connection sequence for partners to begin communication
(defined below) causes each side of the protocol to learn the highest
level of the protocol supported by the party on the other side. If one
party discover that the party on the other end supports a lower version
of the protocol, it is expected that only verbs at the lower version of
the protocol will be used. If an unknown verb is received, the command is
discarded without response.</para>
</section>
<section>
<title>Sequence Numbers</title>
<para>Each packet has a sequence number. Sequence numbers start at 0 and
increment by one with each packet sent. There are separate name spaces
for sequence numbers in each direction, but all packets of all types in a
direction are in the same sequence number name space. The sequence number
is unsigned, and the number following 0xFFFF is 0x0. Sequence numbers are
used to match query packets with query response packets, and for general
debugging.</para>
<para>The sequence numbers in data packets represent a fair amount of
bandwidth overhead, especially if the number of bytes of data per packet
is small in practice. If the performance of this facility is found to be
inadequate due to bandwidth reasons, developers on both sides should
recognize that sequence numbers for data packets represents the
&#8220;low hanging fruit&#8221; to fix that problem, so are cautioned not
to create logical dependencies on sequence numbers for data packets. For
other packet types logical dependencies are acceptable, and indeed are
built into the protocol definition.</para>
<para>
<emphasis role="bold">Implementation Note:</emphasis> Developers should consider field
problem determination in their designs. However, other than providing
packet sequence numbers in the protocol, RAS is outside the scope of the
protocol itself.</para>
</section>
<section>
<title>Flow Control</title>
<para>The partition side of the connection must understand what type or
types of flow control are supported by the platform (physical) side of
the connection. The options are no flow control, software flow control
and hardware flow control.</para>
<para>In version 0 of this protocol it is implied that only software flow
control is implemented by the platform side. If future platforms
implement other options, a new version of this protocol must be created
that includes a verb for the partition side to determine what type or
types of flow control are supported, and to negotiate what type is to be
used in the case that more than one is supported.</para>
</section>
<section>
<title>Packet Type and Verb Summary</title>
<?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
<para>A summary of packet types and verbs can be found in
<xref linkend="dbdoclet.50569375_88851" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569375_88851">
<title>VTERM Packet Type and Verb Summary</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="20*" align="center" />
<colspec colname="c4" colwidth="40*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Packet ID</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Verb ID</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Lowest Version Supported</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>0xFF</para>
</entry>
<entry>
<para>--</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VS_DATA_PACKET_HEADER</para>
</entry>
</row>
<row>
<entry>
<para>0xFE</para>
</entry>
<entry>
<para>--</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VS_CONTROL_PACKET_HEADER</para>
</entry>
</row>
<row>
<entry>
<para>0xFE</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VSV_SET_MODEM_CTL</para>
</entry>
</row>
<row>
<entry>
<para>0xFE</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VSV_MODEM_CTL_UPDATE</para>
</entry>
</row>
<row>
<entry>
<para>0xFE</para>
</entry>
<entry>
<para>0x3</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VSV_RENEGOTIATE_CONNECTION</para>
</entry>
</row>
<row>
<entry>
<para>0xFE</para>
</entry>
<entry>
<para>0x3</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VSV_CLOSE_PROTOCOL (alias for above)</para>
</entry>
</row>
<row>
<entry>
<para>0xFC</para>
</entry>
<entry>
<para>--</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VS_QUERY_RESPONSE_PACKET_HEADER</para>
</entry>
</row>
<row>
<entry>
<para>0xFC</para>
</entry>
<entry>
<para>0x1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VSV_SEND_VERSION_NUMBER</para>
</entry>
</row>
<row>
<entry>
<para>0xFC</para>
</entry>
<entry>
<para>0x2</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VSV_SEND_MODEM_CTL_STATUS</para>
</entry>
</row>
<row>
<entry>
<para>0xFD</para>
</entry>
<entry>
<para>--</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>VS_QUERY_RESPONSE_PACKET_HEADER</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section>
<title>Connection Negotiation</title>
<para>This protocol itself has a state of being open or closed. The state
is &#8220;closed&#8221; at partition boot time and remains closed until a
connection negotiation is initiated by the partition device driver. Once
open, the state remains &#8220;open&#8221; until a VSV_CLOSE_PROTOCOL
command is sent by either side.</para>
<para>While closed, both parties should &#8220;listen&#8221; on the VTY
interface. However, while closed, only query and query response packets
should be acted on; any data or control packets received should be
discarded.</para>
<para>The connection process is initiated by the partition side. The
sequence is as follows:</para>
<itemizedlist>
<listitem>
<para>Both sides are in closed state. Both side are
&#8220;listening&#8221; to the VTY.</para>
</listitem>
<listitem>
<para>The partition sends the VSV_SEND_VERSION_NUMBER query.</para>
</listitem>
<listitem>
<para>The partition continues listening, but discard any packet that is
not a VSV_SEND_VERSION_NUMBER query response.</para>
</listitem>
<listitem>
<para>The platform replies with the VSV_SEND_VERSION_NUMBER query
response packet.</para>
</listitem>
<listitem>
<para>The platform clears any pending data in the serial port
hardware.</para>
</listitem>
<listitem>
<para>The platform sends the VSV_SEND_VERSION_NUMBER query packet.</para>
</listitem>
<listitem>
<para>The partition responds with the VSV_SEND_VERSION_NUMBER query
response packet.</para>
</listitem>
</itemizedlist>
<para>At this point the protocol is open; any data received in the serial
hardware by the platform from this point should be put into data packets
and sent to the partition; any data packets received from the partition
should be sent out the serial hardware.</para>
<para>The platform should implement a time-out after sending a command that
expects a response, and after the time-out log an error. For version 0 of
the protocol an appropriate value would be seconds or minutes; at least 10
seconds. The next version of the protocol should consider a property in the
device tree node to communicate an appropriate time-out value.</para>
</section>
</chapter>