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. Specifically, this protocol is used to allow the Virtual Terminal (VTERM) option, as defined in , as the interface to communicate with a physical serial port which is under control of the platform instead of the OS. 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.

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. The one-byte length field for the packet is the length of the entire packet, including the header byte and the length field itself. 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. For version 0, the following packet headers are defined:

This packet type is used to send data. The data packet is defined in . Packet Offset Member Size (Bytes) Description 0x0 0x1 Packet Header (0xFF) 0x1 0x1 Total size of packet in bytes, including this header 0x2 0x2 Sequence Number (see description below) 0x4 variable Data

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. The control packet is defined in . Packet Offset Member Size (Bytes) Description 0x0 0x1 Packet Header (0xFE) 0x1 0x1 Total size of packet in bytes, including this header 0x2 0x2 Sequence Number (see description below) 0x4 0x2 Control verb (see description below) 0x6 optional and variable Depending on verb, further data The following control verbs are supported.

Protocol Version: 0x00 Note: One-way. This verb is only sent by the partition to the platform. Data Member Definition: The data member for this verb consists of 8 bytes, as defined in . Packet Offset Member Size (Bytes) Description 0x6 0x4 VS_MODEM_CTL word (defined below) 0xA 0x4 VS_MODEM_CTL mask, defining which bits in the control word above are to be updated. 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. The update of the serial port hardware driven by this command must be serialized with data packets. 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 . Bit Position Protocol Version Supported R/O, R/W Name Description 0x0000001 0x00 R/W TSDTR Data Terminal Ready 0x0000020 0x00 R/O TSCD Carrier Detect

Protocol Version: 0x00 Note: One-way. This verb is only sent by the platform to the partition. Data Member Definition: The data member for this verb consists of 4 bytes, as defined in Packet Offset Member Size (Bytes) Description 0x6 0x4 VS_MODEM_CTL word (defined above) 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 . This command should be serialized with data packets. The protocol version in defines the first (lowest) version of the protocol in which a transition of this bit should cause the command to be sent. Bit Name Protocol Version Supported Description TSCD 0x00 A transition of carrier detect must cause this packet to be sent.

Protocol Version: 0x00 Data Member Definition: No data member for this verb. This verb forces the protocol into “closed” state; see the Connection Negotiation section below for the definition and meaning of this state. 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. 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. 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.

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. The query packet is defined in . Packet Offset Member Size (Bytes) Description 0x0 0x1 Packet Header (0xFD) 0x1 0x1 Total size of packet in bytes, including this header (0x6) 0x2 0x2 Sequence Number (see description below) 0x4 0x2 Query verb (see description below) The following query verbs are supported:

Protocol Version: 0x00 Response: The query response data member will contain the one-byte version number of the highest version of the protocol supported by the driver.

Protocol Version: 0x00 Response: The query response data member will contain the four-byte VS_MODEM_CTL word defined above in the VSV_SET_MODEM_CTL verb. Note: One-way. This verb is only sent by the partition to the platform.

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. The query response packet is defined in . Packet Offset Member Size (Bytes) Description 0x0 0x1 Packet Header (0xFC) 0x1 0x1 Total size of packet in bytes, including this header 0x2 0x2 Sequence Number (see description below) 0x4 0x2 Query verb -- matches the query verb for which this is a response 0x6 0x2 Query Sequence Number -- the sequence number of the query packet for which this is a response 0x8 variable Verb-specific response data

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

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. 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. Implementation Note: 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.

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

A summary of packet types and verbs can be found in . Packet ID Verb ID Lowest Version Supported Description 0xFF -- 0 VS_DATA_PACKET_HEADER 0xFE -- 0 VS_CONTROL_PACKET_HEADER 0xFE 0x1 0 VSV_SET_MODEM_CTL 0xFE 0x2 0 VSV_MODEM_CTL_UPDATE 0xFE 0x3 0 VSV_RENEGOTIATE_CONNECTION 0xFE 0x3 0 VSV_CLOSE_PROTOCOL (alias for above) 0xFC -- 0 VS_QUERY_RESPONSE_PACKET_HEADER 0xFC 0x1 0 VSV_SEND_VERSION_NUMBER 0xFC 0x2 0 VSV_SEND_MODEM_CTL_STATUS 0xFD -- 0 VS_QUERY_RESPONSE_PACKET_HEADER

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. 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. The connection process is initiated by the partition side. The sequence is as follows: Both sides are in closed state. Both side are “listening” to the VTY. The partition sends the VSV_SEND_VERSION_NUMBER query. The partition continues listening, but discard any packet that is not a VSV_SEND_VERSION_NUMBER query response. The platform replies with the VSV_SEND_VERSION_NUMBER query response packet. The platform clears any pending data in the serial port hardware. The platform sends the VSV_SEND_VERSION_NUMBER query packet. The partition responds with the VSV_SEND_VERSION_NUMBER query response packet. 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. 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.