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.
1062 lines
38 KiB
XML
1062 lines
38 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
Copyright (c) 2016, 2020 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<appendix 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 appendix 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 valign="middle" >
|
|
<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 valign="middle" >
|
|
<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 valign="middle" >
|
|
<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 valign="middle" >
|
|
<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 valign="middle" >
|
|
<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 “closed” 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 valign="middle" >
|
|
<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 valign="middle" >
|
|
<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 “least
|
|
common denominator” 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
|
|
“low hanging fruit” 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 valign="middle" >
|
|
<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 “closed” at partition boot time and remains closed until a
|
|
connection negotiation is initiated by the partition device driver. Once
|
|
open, the state remains “open” until a VSV_CLOSE_PROTOCOL
|
|
command is sent by either side.</para>
|
|
<para>While closed, both parties should “listen” 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
|
|
“listening” 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>
|
|
</appendix>
|