diff --git a/Virtualization/ch_lpar_option.xml b/Virtualization/ch_lpar_option.xml
index fc89056..40e35e5 100644
--- a/Virtualization/ch_lpar_option.xml
+++ b/Virtualization/ch_lpar_option.xml
@@ -1023,6 +1023,46 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
Reset interrupt state to the initial state
+
+
+
+ /
+
+
+
+ Open a terminal session with a Vterm IOA
+
+
+
+
+
+ /
+
+
+
+ Get data from a Vterm session
+
+
+
+
+
+ /
+
+
+
+ Put data to a Vterm session
+
+
+
+
+
+ /
+
+
+
+ Close an existing session with a Vterm IOA
+
+
@@ -4638,6 +4678,82 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
hcall-int-exploitation
+
+
+
+ /
+
+
+
+ 0x408
+
+
+ Normal
+
+
+ If VSM is implemented
+
+
+ hcall-vsm
+
+
+
+
+
+ /
+
+
+
+ 0x40C
+
+
+ Critical
+
+
+ If VSM is implemented
+
+
+ hcall-vsm
+
+
+
+
+
+ /
+
+
+
+ 0x410
+
+
+ Critical
+
+
+ If VSM is implemented
+
+
+ hcall-vsm
+
+
+
+
+
+ /
+
+
+
+ 0x414
+
+
+ Normal
+
+
+ If VSM is implemented
+
+
+ hcall-vsm
+
+
hcalls to support an Ultravisor
@@ -10940,7 +11056,7 @@ hcall ( const uint64 H_INT_GET_SOURCE_INFO, /* Returns the logical real address
H_INT_SET_SOURCE_CONFIG
The H_INT_SET_SOURCE_CONFIG hcall() is used to assign a Logical Interrupt
- Source to a target. The Logical In- terrupt Source is designated with the
+ Source to a target. The Logical Interrupt Source is designated with the
“lisn” parameter and the target is designated with the “target” and
“priority” parameters. Upon return from the hcall(), no additional interrupts
will be directed to the old EQ. The old EQ should be investigated for
@@ -10994,7 +11110,7 @@ hcall ( const uint64 H_INT_SET_SOURCE_CONFIG, /* Assigns */
way of unmasking and restoring the source. Thus this should only
be used in interrupts that are also masked at the source, and
only in cases where the interrupt is not meant to be used for
- a large amount of time be- cause no valid target exists for it
+ a large amount of time because no valid target exists for it
for example
diff --git a/Virtualization/ch_virtual_io.xml b/Virtualization/ch_virtual_io.xml
index 0073faf..863b173 100644
--- a/Virtualization/ch_virtual_io.xml
+++ b/Virtualization/ch_virtual_io.xml
@@ -13999,6 +13999,1243 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne
+
+ Vterm Multiplex
+
+ Virtual Serial Multiplex (VSM) IOA allows a highly-privileged logical
+ partition to serve multiple simultaneous partner partition's client Vterm
+ IOAs. Management consoles are able to indirectly interact with a single VSM
+ IOA to access multiple simultaneous partner partition's client virtual serial
+ sessions up to a maximum number of simultaneous connections.
+
+ VSM support is provided by code running in a highly-privileged logical
+ partition that uses the mechanisms of the Reliable Command/Response Transport
+ (single sided) and an extended class of Vterm HCALLs to manage, service, and
+ send virtual serial traffic to platform code.
+
+ The VSM architecture is built upon the architecture specified in the
+ following sections:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Virtual Serial Multiplex General
+
+ This section contains an informative outline of the architectural
+ intent of use of VSM.
+
+ A highly-privileged partition's device tree contains one node notifying
+ the partition that it has been assigned one VSM adapter. The node's
+ “type”
+ and
+ “compatible”
+ properties notify the partition that the virtual adapter is a Virtual Serial
+ Multiplex adapter. The unit address of the node is used by the partition to
+ map the virtual device to the OS's corresponding logical representation. The
+ node's
+ “interrupts”
+ property specifies the interrupt source number that has
+ been assigned to the VSM for data received on the response queue. The partition,
+ uses the hcall()s associated with the Reliable Command/Response Transport
+ facility to register and deregister its CRQ, manage notification of responses,
+ and send command requests to the platform. A single sided CRQ is implemented
+ for the VSM adapter. All command requests sent to the platform via H_SEND_CRQ
+ are processed immediately under the H_SEND_CRQ context.
+
+
+ VSM Initialization
+
+ The device driver, when configured and opened, allocates memory for
+ its request queue (an array, large enough for all possible outstanding
+ requests, of 16 byte elements). The driver then pins the queue and maps
+ it into I/O space, via the kernel’s I/O mapping services that invoke
+ the H_PUT_TCE hcall(), using the first window pane specified in the
+ “ibm,my-dma-window”
+ property. The queue is then registered using the H_REG_CRQ hcall().
+ Finally the device driver registers to receive control when the interrupt
+ source specified in the virtual IOA’s device tree node signals.
+
+ Once the CRQ is setup, the device driver queues an Initialization
+ Command/Response with the second byte of “Initialize” in order to attempt
+ to tell the platform side that everything is setup on the partition side.
+ The response to this send may be that the send has been dropped or has
+ successfully been sent. If successful, the sender should expect back an
+ Initialization Command/Response with a second byte of
+ “Initialization Complete,” at which time the communication path can be
+ deemed to be open. If dropped, then the sender waits for the receipt
+ of an Initialization Command/Response with a second byte of “Initialize,”
+ at which time an “Initialization Complete” message is sent, and if that
+ message is sent successfully, then the communication path can be deemed
+ to be open.
+
+ The device driver then queues a Version Exchange message to
+ handshake with the platform and determine any version compatibility.
+ If successful, the sender should expect back an Version Exchange Response.
+
+
+ This architecture does not specify the payload format of the requests or
+ responses. However, the architectural intent is supplied in the following
+ tables for reference.
+
+
+ CRQ Message Protocols (Virtual Serial Multiplex IOA)
+
+
+
+
+
+
+
+
+
+ Byte Offset
+
+
+
+
+ Field Name
+
+
+
+
+ Subfield Name
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ 0
+
+
+ Header
+
+
+
+
+
+ Contains Element Valid Bit plus Event Type Encodings (see
+ ).
+
+
+
+
+ 1
+
+
+ Payload
+
+
+ Command/ Transport Event Code
+
+
+ For Valid Command Response Entries, see
+ .
+ For Transport Event Codes see
+ .
+
+
+
+
+ 2-15
+
+
+
+
+
+ Format Dependent
+
+
+
+
+
+
+
+
+ Example Reliable CRQ Entry Command Byte Definitions for VSM
+
+
+
+
+
+
+
+ Command Byte Value
+
+
+
+
+ Definition
+
+
+
+
+
+
+
+ 0x01
+
+
+ Version Exchange
+
+
+
+
+ 0x81
+
+
+ Version Exchange Response
+
+
+
+
+ 0x02
+
+
+ Signal VTERM Interrupt
+
+
+
+
+ 0x82
+
+
+ Signal VTERM Interrupt Response
+
+
+
+
+ 0x03
+
+
+ Error Indication
+
+
+
+
+ 0x04 - 0xFF
+
+
+ Reserved
+
+
+
+
+
+
+
+
+ Example Version Exchange Queue Element for VSM
+
+
+
+
+
+
+
+
+ Byte Offset
+
+
+
+
+ Field Value
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ 0
+
+
+ 0x80
+
+
+ Valid Header
+
+
+
+
+ 1
+
+
+ 0x01
+
+
+ Version Exchange (Response: 0x81)
+
+
+
+
+ 2-3
+
+
+
+
+
+ Version
+
+
+
+
+ 4-15
+
+
+ NA
+
+
+ Reserved
+
+
+
+
+
+
+
+
+ Example Signal VTERM Interrupt Queue Element for VSM
+
+
+
+
+
+
+
+
+ Byte Offset
+
+
+
+
+ Field Value
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ 0
+
+
+ 0x80
+
+
+ Valid Header
+
+
+
+
+ 1
+
+
+ 0x02
+
+
+ Signal Interrupt (Response: 0x82)
+
+
+
+
+ 2-7
+
+
+ NA
+
+
+ Reserved
+
+
+
+
+ 8-15
+
+
+
+
+
+ Console-token
+
+
+
+
+
+
+
+
+ Example Error Indication Queue Element for VSM
+
+
+
+
+
+
+
+
+ Byte Offset
+
+
+
+
+ Field Value
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ 0
+
+
+ 0x80
+
+
+ Valid Header
+
+
+
+
+ 1
+
+
+ 0x03
+
+
+ Error Indication
+
+
+
+
+ 2-3
+
+
+ NA
+
+
+ Reserved
+
+
+
+
+ 4-5
+
+
+
+
+
+ Error Cause. This field contains a value as detailed in
+
+ showing the cause of the error.
+
+
+
+
+ 6-7
+
+
+
+
+
+ Internal Error Detail. This field contains details defined
+ internally to help narrow down the scope of the Error Cause.
+
+
+
+
+ 8-15
+
+
+ NA
+
+
+ Reserved
+
+
+
+
+
+
+
+
+ Error Cause
+
+
+
+
+
+
+
+ Value
+
+
+
+
+ Definition
+
+
+
+
+
+
+
+ 0x01
+
+
+ Firmware Problem
+
+
+
+
+ 0x02
+
+
+ Device Driver Problem
+
+
+
+
+ 0x03 - 0xFFFF
+
+
+ Reserved
+
+
+
+
+
+
+
+
+ Open Virtual Serial Session Request
+
+ Partition receives a request to open the virtual serial session
+ for a client partner partition's Vterm IOA.
+
+
+
+ Partition uses the H_OPEN_VTERM_LP hcall with the client partner
+ partition's LP ID and session ID as parameters.
+
+
+
+ On successful open, the partition receives a console-token that
+ represents the handle of the client LP and session.
+
+
+
+
+
+ Receive Char Event
+
+ The partition receives an interrupt when a valid command(s) is/are
+ received on the response queue.
+
+
+
+ The partition is notified of Vterm receive data for a specific
+ client partner partition's LP ID and session (console-token handler)
+ via the response queue.
+
+
+
+ The partition uses the H_GET_TERM_CHAR_LP hcall() with the token
+ handler to receive data from the client Vterm IOA.
+
+
+
+ The partition continues to call H_GET_TERM_CHAR_LP with the token
+ handler until H_Success is returned with zero count of characters
+ specified in R4.
+
+
+
+ The partition replies to notification CRQ message with a “done”
+ CRQ response w/ the token handler. This essentially behaves like
+ the H_EOI for the connection represented by the console-token handler.
+ Race conditions could occur in any situation; therefore, the
+ partition should again call H_GET_TERM_CHAR_LP w/ the token handler
+ to verify the queue is empty.
+
+
+
+
+
+ Send Char Event
+
+ Partition wishes to send a char or string to a specific client
+ partner partition's LP ID and session (console-token handler).
+
+
+
+ Partition uses the H_PUT_TERM_CHAR_LP with the unit-address of
+ the VSM adapter, the token representing the handle of the client LP
+ and session, the length of the string to transmit, and the string
+ to send in char0_7 and char8_15.
+
+
+
+
+
+ Close Virtual Serial Session Request
+
+ Partition receives a request to close the virtual serial session.
+
+
+
+ Partition uses the H_CLOSE_VTERM_LP HCALL with console-token
+ handler as a parameter.
+
+
+
+
+
+ VSM Device Driver Close
+
+
+
+ Partition uses the H_FREE_CRQ hcall().
+
+
+
+ The platform “closes” any valid virtual serial sessions and
+ de-registers each.
+
+
+
+
+
+
+ Virtual Serial Multiplex Requirements
+
+ This normative section provides the general requirements for the
+ support of VSM.
+
+
+
+ R1--1.
+
+ For the VSM option: The
+ platform must implement the single sided Reliable Command/Response
+ Transport option as defined in
+ .
+
+
+
+
+ R1--2.
+
+ For the VSM option: The platform
+ must implement a new class of VTERM hcalls() as defined in
+ .
+
+
+
+
+ In addition to the firmware primitives, and the structures they define,
+ the partition’s OS needs to know specific information regarding the
+ configuration of the virtual IOAs that it has been assigned so that
+ it can load and configure the correct device driver code. This information
+ is provided by the Open Firmware device tree node associated with the
+ virtual IOA (see
+ ).
+
+
+
+ Virtual Serial Multiplex hcalls()
+
+ The following hcall()s are used to send data to and get data from
+ both the client and sever Vterm IOAs.
+
+
+ H_OPEN_VTERM_LP
+
+
+ Syntax:
+
+
+
+
+
+ Parameters:
+
+
+
+ unit-address: The unit address of the VSM IOA, from the
+ “reg”
+ property of the VSM IOA.
+
+
+
+ partner-session-id: The partner session ID to which to be connected
+
+
+
+ partner-partition-id: The partition ID to which to be connected.
+
+
+
+
+
+ Semantics:
+
+
+
+ Hypervisor checks the unit-address parameter for validity
+ against the VSM IOA unit address assigned to the partition, else
+ return H_Parameter.
+
+
+
+ Hypervisor returns H_Parameter if it detects that the virtual
+ console associated with the partner-session-id and
+ partner-partition-id pair could not be found or is not valid.
+
+
+
+ Hypervisor returns H_Parameter if it detects that the virtual
+ console associated with the partner-session-id and
+ partner-partition-id pair is already active or migrating.
+
+
+
+ Hypervisor returns H_State if the VSM CRQ has not been
+ registered successfully.
+
+
+
+ Hypervisor returns H_State if the VSM has not successfully
+ completed the version exchange handshake.
+
+
+
+ Hypervisor returns H_Resource if the maximum number of
+ simultaneous virtual serial sessions has been exceeded.
+
+
+
+ Hypervisor returns an H_Busy, H_LongBusyOrder1mSec, or
+ H_LongBusyOrder10mSec, software must call H_OPEN_VTERM_LP
+ again with the same parameters. Software may choose to treat
+ H_LongBusyOrder1mSec and H_LongBusyOrder10mSec the same as H_Busy
+
+
+
+ Else, make a multiplex connection between the VSM IOA specified
+ by unit-address and the partner Vterm IOA specified by the
+ partner-partition-id and partner-session-id pair, allowing
+ future H_PUT_TERM_CHAR_LP and H_GET_TERM_CHAR_LP operations to
+ flow between the two Vterm IOAs, and return H_Success.
+
+
+
+ Upon return with H_Success register R4 contains the
+ console-token to be used as a handle for future H_PUT_TERM_CHAR_LP,
+ H_GET_TERM_CHAR_LP, and H_CLOSE_VTERM_LP operations along with
+ applicable CRQ messages for the VSM IOA.
+
+
+
+
+
+
+ H_PUT_TERM_CHAR_LP
+
+
+ Syntax:
+
+
+
+
+
+ Parameters:
+
+
+
+ unit-address: The unit address of the VSM IOA, from the
+ “reg”
+ property of the VSM IOA.
+
+
+
+ console-token: The console token received from H_OPEN_VTERM_LP
+ crq response
+
+
+
+ len: The length of the string to transmit through the virtual
+ terminal port. Valid values are in the range of 0-16.
+
+
+
+ char0_7 and char8_15: The string starts in the high order byte
+ of register R7 and proceeds toward the low order byte in register R8
+
+
+
+
+
+ Semantics:
+
+
+
+ Hypervisor checks the unit-address parameter for validity
+ against the VSM IOA unit address assigned to the partition,
+ else return H_Parameter.
+
+
+
+ Hypervisor returns H_Hardware if it detects that the virtual
+ console terminal connection is not working.
+
+
+
+ Hypervisor returns H_Closed if it detects that the virtual
+ console associated with the console-token parameter is not
+ open or not currently valid.
+
+
+
+ If the length parameter is outside of the values 0-16 the
+ hypervisor immediately returns H_Parameter with no other action.
+
+
+
+ If the partition’s virtual console terminal buffer has room
+ for the entire string, the hypervisor queues the output string and
+ returns H_Success. Note: There is always room for a zero-length
+ string (a zero length write can be used to test the virtual console
+ terminal connection).
+
+
+
+ If the buffer cannot hold the entire string, no data is
+ enqueued and the return code is H_Busy.
+
+
+
+
+
+
+ H_GET_TERM_CHAR_LP
+
+
+ Syntax:
+
+
+
+
+
+ Parameters:
+
+
+
+ unit-address: The unit address of the VSM IOA, from the
+ “reg”
+ property of the VSM IOA.
+
+
+
+ console-token: The console token received from H_OPEN_VTERM_LP
+ crq response
+
+
+
+
+
+ Semantics:
+
+
+
+ Hypervisor checks the unit-address parameter for validity against
+ the VSM IOA unit address assigned to the partition, else return
+ H_Parameter.
+
+
+
+ Hypervisor returns H_Hardware if it detects that the virtual
+ console terminal connection is not working.
+
+
+
+ Hypervisor returns H_Closed if it detects that the virtual
+ console associated with the console-token parameter is not
+ open or not currently valid.
+
+
+
+ Hypervisor returns H_Success in all other cases, returning
+ maximum number of characters available in the partition’s virtual
+ console terminal input buffer (up to 16) -- a len value of 0
+ indicates that the input buffer is empty.
+
+
+
+ Upon return with H_Success register R4 contains the number of
+ bytes (if any) returned in registers R5 and R6.
+
+
+
+ Upon return with H_Success the return character string starts
+ in the high order byte of register R5 and proceeds toward the low
+ order byte in register R6 for the number of characters specified
+ in R4. The contents of all other byte locations of registers R5
+ and R6 are undefined.
+
+
+
+
+
+
+ H_CLOSE_VTERM_LP
+
+
+ Syntax:
+
+
+
+
+
+ Parameters:
+
+
+
+ unit-address: The unit address of the VSM IOA, from the
+ “reg”
+ property of the VSM IOA.
+
+
+
+ console-token: The console token received from H_OPEN_VTERM_LP
+ hcall response
+
+
+
+
+
+ Semantics:
+
+
+
+ Hypervisor checks the unit-address parameter for validity against
+ the VSM IOA unit address assigned to the partition, else return
+ H_Parameter.
+
+
+
+ Hypervisor returns H_Closed if it detects that the virtual
+ console associated with the console-token parameter is not open
+ or not currently valid.
+
+
+
+ Hypervisor returns an H_Busy, H_LongBusyOrder1mSec, or
+ H_LongBusyOrder10mSec, software must call H_CLOSE_VTERM_LP
+ again with the same parameters. Software may choose to treat
+ H_LongBusyOrder1mSec and H_LongBusyOrder10mSec the same as H_Busy
+
+
+
+ Else, break the multiplex connection between the VSM IOA
+ specified by unit-address and the partner Vterm IOA specified by
+ the console-token, and return H_Success.
+
+
+
+
+
+
+ Virtual Serial Multiplex Device Tree Node
+
+
+
+ R1--1.
+
+ For the VSM option: The platform's
+ OF device tree must include as a child of the /vdevice node,
+ one node of type “vty-mserver”.
+
+
+
+
+ R1--2.
+
+ For the VSM option: The platform's
+ vty-mserver OF node must contain properties defined in
+
+ (other standard I/O adapter properties are permissible as appropriate).
+
+
+
+
+
+ Properties of the vty-mserver Node (Virtual Serial Multiplex IOA)
+
+
+
+
+
+
+
+
+ Property Name
+
+
+
+
+ Required?
+
+
+
+
+ Definition
+
+
+
+
+
+
+
+ “name”
+
+
+ Y
+
+
+ Standard property name per IEEE 1275 specifying the virtual
+ device name, the value shall be
+ “vty-mserver”.
+
+
+
+
+ “device_type”
+
+
+ Y
+
+
+ Standard property name per IEEE 1275 specifying the virtual
+ device type, the value shall be
+ “serial-multiplex”.
+
+
+
+
+ “model”
+
+
+ NA
+
+
+ Property not present.
+
+
+
+
+ “compatible”
+
+
+ Y
+
+
+ Standard property name per IEEE 1275 specifying the programming
+ models that are compatible with this virtual IOA, the value shall be
+ “IBM,serial-multiplex”.
+
+
+
+
+ “used-by-rtas”
+
+
+ N
+
+
+ Property not present.
+
+
+
+
+ “ibm,loc-code”
+
+
+ Y
+
+
+ Property name specifying the unique and
+ persistent location code associated with this virtual IOA
+ presented as an encoded array as with
+ encode-string.
+ The value shall be of the form specified in
+ information on
+ Virtual Card Connector Location Codes.
+
+
+
+
+ “reg”
+
+
+ Y
+
+
+ Standard property name per IEEE 1275 specifying the
+ register addresses, used as the unit address (unit
+ ID), associated with this virtual IOA presented as
+ an encoded array as with encode-phys.
+ Because this virtual IOA's parent, /vdevice, has
+ “#address-cells”
+ value of 1 and
+ “#size-cells”
+ value of 0, the
+ “reg”
+ property value for this device consists of a single cell.
+
+
+
+
+ “ibm,my-dma-window”
+
+
+ Y
+
+
+ Property name specifying the DMA window
+ associated with this virtual IOA presented as an encoded
+ array of two sets (two window panes) of three values (LIOBN, phys, size) encoded as with
+ encode-int,
+ encode-phys, and
+ encode-int respectively.
+
+
+
+
+ “interrupts”
+
+
+ Y
+
+
+ Standard property name specifying the interrupt source
+ number and sense code associated with this virtual
+ IOA presented as an encoded array of two cells encoded as with
+ encode-int with the first cell
+ containing the interrupt source number, and the
+ second cell containing the sense code 0 indicating positive
+ edge triggered. The interrupt source number being the value
+ returned by the H_XIRR or H_IPOLL hcall().
+
+
+
+
+ “ibm,my-drc-index”
+
+
+ For DR
+
+
+ Present if the platform implements DR for this node.
+
+
+
+
+ “ibm,#dma-size-cells”
+
+
+ See Definition Column
+
+
+ Property name, to define the package’s dma address
+ size format. The property value specifies the number
+ of cells that are used to encode the size field of
+ dma-window properties. This property is present when the
+ dma address size format cannot be derived using
+ the method described in the definition for the
+ “ibm,#dma-size-cells”
+ property in
+ section on System Bindings.
+
+
+
+
+ “ibm,#dma-address-cells”
+
+
+ See Definition Column
+
+
+ Property name, to define the package’s dma address
+ format. The property value specifies the number
+ of cells that are used to encode the physical address field of
+ dma-window properties. This property is present when the
+ dma address format cannot be derived using
+ the method described in the definition for the
+ “ibm,#dma-address-cells”
+ property in
+ section on System Bindings.
+
+
+
+
+
+
+
+