<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>