diff --git a/Virtualization/ch_lpar_option.xml b/Virtualization/ch_lpar_option.xml
index 3f8dafb..2a34c34 100644
--- a/Virtualization/ch_lpar_option.xml
+++ b/Virtualization/ch_lpar_option.xml
@@ -1292,19 +1292,35 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
thread
-
+
+
+
+ /
+
+
+
+ Use the calling processor to perform platform operations.
+
+
+
+
+ /
+
+
+
+ Transition VASI operation stream state.
+
+
+
+
+
+ /
+
+
+
+ Return the VASI operation stream state.
+
+
@@ -3224,28 +3240,63 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
hcall-join
-
+
+
+
+ /
+
+
+
+ 0x29C
+
+
+ Normal
+
+
+ If VASI option is implemented
+
+
+ hcall-vasi
+
+
+
+
+
+ /
+
+
+
+ 0x2A0
+
+
+ Normal
+
+
+ If VASI option is implemented
+
+
+ hcall-vasi
+
+
+
+
+
+ /
+
+
+
+ 0x2A4
+
+
+ Normal
+
+
+ If VASI option is implemented
+
+
+ hcall-vasi
+
+
@@ -14804,12 +14855,10 @@ hcall ( const uint64 H_HOME_NODE_ASSOCIATIVITY), /* Returns in R4-R9 the home no
R1--2.
-
- Reserved
+ For the Partition Migration and Partition
+ Hibernation options: The platform must implement the VASI
+ option (See ).
+
diff --git a/Virtualization/ch_virtual_io.xml b/Virtualization/ch_virtual_io.xml
index 2cc6cb7..a6a20b3 100644
--- a/Virtualization/ch_virtual_io.xml
+++ b/Virtualization/ch_virtual_io.xml
@@ -1228,10 +1228,9 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */
xrefstyle="select: labelnumber nopage"/>-8.
-
- Reserved
+ For the SMC options:
+ The platform must specify the ASQ interrupt as the second interrupt in the
+ “interrupts” property for a virtual IOA.
@@ -1312,15 +1311,14 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */
xrefstyle="select: labelnumber nopage"/>-14.
-
- Reserved
+ For the SMC option:
+ There must exist three triples (three window panes) in the
+ “ibm,my-dma-window”
+ property of all partitions which contain an SMC virtual IOA, and the size field
+ of the second triple (second window pane) of an
+ “ibm,my-dma-window” property must be equal to the
+ size field of the corresponding third triple (third window pane) of the associated partner partition’s
+ “ibm,my-dma-window” property.
@@ -3267,7 +3265,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
Validate that the given virtual IOA is a ILLAN adapter with the
- "ibm,trunk-adapter", else return H_Parameter.
+ “ibm,trunk-adapter”, else return H_Parameter.
@@ -3297,7 +3295,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
Validate that the given virtual IOA is a ILLAN adapter with the
- "ibm,trunk-adapter", else return H_Parameter.
+ “ibm,trunk-adapter”, else return H_Parameter.
@@ -13060,6 +13058,3682 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne
+
+ Virtual Management Channel (VMC)
+
+ PAPR Virtual Management Channel (VMC) support is provided
+ by code running in a logical partition that uses the
+ mechanisms of the Reliable Command/Response Transport and
+ Logical Remote DMA of the Synchronous VIO Infrastructure
+ to service and to send requests to platform code. The
+ purpose of this interface is to communicate platform
+ management information between designated logical
+ partition and the platform.
+
+ The VMC architecture is built upon the architecture specified in the following sections:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Virtual Management Channel Requirements
+
+ This normative section provides the general requirements for the support of VMC.
+
+
+
+ R1--1.
+
+ For the VMC option:The platform must
+ implement the Reliable Command/Response Transport option
+ as defined in .
+
+
+
+
+ R1--2.
+
+ For the VMC option:The platform must
+ implement the Logical Remote DMA option 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 ).
+
+
+
+
+ Partition Virtual Management Channel Device Tree Node
+
+ Partition VMC IOA nodes have no children nodes.
+
+
+
+ R1--1.
+
+ For the VMC option: The platform’s
+ Open Firmware device tree for client partitions must include as
+ a child of the /vdevice
+ node, a node of type “vmc” as the
+ parent of a sub-tree representing the virtual IOAs
+ assigned to the partition.
+
+
+
+
+ R1--2.
+
+ For the VMC option: The platform’s
+ vmc
+ Open Firmware node must contain properties as defined in
+
+ (other standard I/O adapter properties are permissible as appropriate).
+
+
+
+
+
+ Properties of the VMC Node in the Client Partition
+
+
+
+
+
+
+
+
+ Property Name
+
+
+
+
+ Required?
+
+
+
+
+ Definition
+
+
+
+
+
+
+
+ “name”
+
+
+ Y
+
+
+ Standard property name per IEEE 1275 specifying the virtual
+ device name, the value shall be
+ “ibm,vmc”.
+
+
+
+
+ “device_type”
+
+
+ Y
+
+
+ Standard property name per IEEE 1275 specifying the virtual
+ device type, the value shall be
+ “ibm,vmc”.
+
+
+
+
+ “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,vmc”.
+
+
+
+
+ “used-by-rtas”
+
+
+ See Definition Column
+
+
+ Present if appropriate.
+
+
+
+
+ “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 of length
+ “#address-cells”
+ value shall be 0xwhatever (virtual
+ “reg”
+ property used for unit address no actual locations used, therefore, the size field
+ has zero cells (does not exist) as determined by the value of the
+ “#size-cells” property).
+
+
+
+
+ “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.
+ Of these two triples, the first describes the window
+ pane used to map server partition (the
+ designated management partition) memory, the second is the
+ window pane through which the client partition
+ (the platform partition) maps its memory that it makes
+ available to the server partition.
+
+
+
+
+ “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.
+
+
+
+
+
+
+
+
+
+
+ Virtual Asynchronous Services Interface (VASI)
+
+ The PAPR Virtual Asynchronous Services Interface (VASI)
+ allows an authorized virtual server partition (VSP) to
+ safely access the internal state of a specific partition.
+ The access provided by VASI enables high level administrative
+ services such as partition migration, hibernation and
+ virtualization of partition logical real memory. VASI uses the
+ mechanisms of the Reliable Command/Response Transport a
+ nd Logical Remote DMA of the Synchronous VIO Infrastructure
+ to service requests.
+
+ VASI is built upon the architecture specified in the following sections:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Overview
+
+
+ VASI Streams, Services and States
+
+ A single VASI virtual IOA may be capable of supporting
+ multiple streams of operations (up to the number presented in the
+ “ibm,#vasi-streams”
+ property, see
+ )
+ each representing a specific high level operation such as an
+ individual logical partition migration, or a unique logical
+ partition hibernation, etc. The hypervisor and the various
+ logical partitions use the VASI_Stream_ID as a handle to associate
+ the services that each provide to the specific high level function.
+ Similarly a single VASI virtual IOA may be
+ capable of supporting multiple service sessions (opens) for
+ each VASI_Stream_ID (up to the number negotiated by the
+ #Opens field of the capabilities string, see
+ ).
+
+ VASI streams and individual service sessions may be in
+ one of several states. Refer to the specific high level function description in
+
+ for the state descriptions and transition triggers that are defined for each high level function.
+
+
+
+
+ VASI Handles
+
+ VASI defines several versions of handles. The VASI Stream
+ ID is used to associate the elements of the same high level
+ function (such as a specific partition migration operation).
+ In this case, the various partitions are assigned roles and a
+ VASI Stream ID. By opening a VASI virtual IOA with a given
+ VASI Stream ID and Service parameter, the partition declares
+ its intent to perform the specified service for the specific
+ high level operation. By means outside the scope of
+ PAPR, the platform is told to expect such service from the
+ specific partition; thus when the match happens, the high
+ level operation is enabled. At open time, the platform and
+ partition negotiate a pair of convenient handles to use as a
+ substitute for the architecturally opaque VASI Stream ID.
+ This pair of 4 byte handles are called the TOP/BOTTOM.
+ The TOP field is used by the partition to denote its
+ operations for the specific VASI Stream ID, while the BOTTOM
+ field provides that function for the platform firmware.
+
+ The first 8 bytes of a VASI data buffer are reserved for
+ Virtual Server Partition (VSP) use as the buffer correlator field.
+ The buffer correlator field is architecturally opaque. The
+ architectural intent is that the buffer correlator field is a VSP
+ handle to the data buffer control block.
+
+
+
+
+ Semantic Conventions
+
+ The convention for the specification of VASI CRQ message
+ processing semantics is via a specifically ordered sequence
+ of operations. Implementations are not required to code in these
+ sequences but are required to appear as if they
+ did. In general, parameters and operational state are first
+ verified, followed by the operation to be performed if all the
+ parameter/state checks succeed. If a check fails, a response is
+ generated at that point and further processing of the message
+ is abandoned. Note that standard CRQ processing operations
+ (message enqueue and dequeue processing such as
+ finding the next valid message, resetting the
+ valid message bit when processing is complete, etc. (See
+ )
+ are assumed and not explicitly included in the semantic
+ specification.
+
+
+
+
+
+ VASI Data Buffers (Normative)
+
+ Data buffers used by VASI are defined as from ILLAN (See
+ ).
+ VASI references data buffers via a valid buffer descriptor (Control
+ Byte = 0x80) as from ILLAN (See
+ ).
+ relative to first pane of the VASI virtual IOA
+ “ibm,my-dma-window” property. The first 8 bytes of a
+ data buffer are reserved for an OS opaque handle.
+ A filled data buffer contains either a VASI Download Request
+ Specifier or a VASI Operation Request Specifier; refer to
+ or
+
+ respectively, following the opaque handle. Buffers are supplied to
+ the VASI virtual IOA via the VASI Add Buffer CRQ request message,
+ and returned to the VASI device driver in operation requests such as the VASI
+ Operation CRQ request message or, for those that have not
+ been used by operation requests, via responses to the VASI
+ Free Buffer CRQ request message. Closing a VASI service
+ session releases buffers queued for that service session in
+ the VASI virtual IOA, while deregistering the VASI virtual
+ IOA CRQ does the same for all of the VASI virtual IOA
+ service sessions.
+
+
+
+ R1--1.
+
+ For the VASI option: The platform
+ must implement the Reliable Command/Response Transport option (See
+ ).
+
+
+
+
+ R1--2.
+
+ For the VASI option: The storage
+ for VASI data buffers to be used by a given VASI virtual IOA
+ must be TCE mapped within the first pane of the
+ “ibm,my-dma-window”
+ property as presented in the device
+ tree node of the VASI virtual IOA Open Firmware
+ device tree node.
+
+
+
+
+ R1--3.
+
+ For the VASI option: Firmware must
+ not modify the first 8 bytes (Buffer Correlator field) of a VASI data buffer.
+
+
+
+
+ R1--4.
+
+ For the VASI option: Immediately following
+ the first 8 bytes of a filled VASI data buffer must be either
+ a VASI Download Request Specifier or a VASI Operation Request Specifier.
+
+
+
+
+ R1--5.
+
+ For the VASI option: The VASI Download
+ Request Specifier must be formatted as per
+ .
+
+
+
+
+ R1--6.
+
+ For the VASI option: The VASI Operation
+ Request Specifier must be formatted as per
+ .
+
+
+
+
+
+ VASI Download Request Specifier
+
+ The VASI Download Request Specifier is presented in
+ .
+ The VASI Download Request Specifier is used with the VASI Download Request
+ message see
+ .
+
+
+ VASI Download Request Specifier structure
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Operation Request Specifier
+
+ The VASI Operation Request Specifier is presented in
+ .
+ The TOP/BOTTOM (8 bytes) field is a pair of 4 byte opaque handles
+ as negotiated by the VASI Open Request/Response pair see
+ .
+
+
+ Expected Semantics of VASI operation requests:
+
+ Operation length is communicated by the summation of the
+ lengths of the buffer segment control structures following
+ the operation correlator field.
+
+
+ Operations that write at the end of the file normally
+ extend the file. If extending the file is not possible due to resource
+ constraints, then the operation is aborted at the end of
+ the file, the VASI operation response message carries
+ the “End of File” status with the Residual field containing
+ the number of requested bytes that were not transferred
+ (Residual value of all ones indicates Residual field overflow).
+
+
+ Read operations that access beyond the end of the file are
+ aborted at the end of the file. The VASI operation response
+ message carries the “End of File” status with the Residual
+ field containing the number of requested bytes
+ that were not transferred (Residual value of all
+ ones indicates Residual field overflow).
+
+
+ Sequential writes deliver the input stream of bytes to the
+ receiver in the same order, but not necessarily in the same
+ blocking as originated by the sender.
+
+
+ Index operations carry the additional semantic over the
+ corresponding sequential operation that they are a collection
+ of one or more sub-operations of the same type (read/write).
+ Each sub-operation specification starts with a
+ control field encoding of 0xC0 that carries the 512
+ byte file block index of the start of the operation. The file cursor
+ can then be adjusted within the block using a control
+ field of 0x40 followed by a 3 byte binary offset (legal
+ values 0-511). This offset allows operations to beginning
+ on any byte boundary within the specified 512 byte
+ block index. The remainder of each sub-operation
+ specification is a scatter gather list. The sub-operation length is
+ defined by the number of bytes of data/buffer
+ supplied in the sub-operation scatter gather list.
+
+
+ The “Hardware” status code indicates a failure due to
+ any hardware problem including physical I/O.
+
+
+ The “Invalid Buffer Correlator” status code is reserved
+ for failure to find the operation buffer.
+
+
+ The “Invalid VASI Operation Request Specifier” status
+ code is used for any failure in the decode of the operation
+ buffer not specifically called out by a previous semantic.
+
+
+ The first control field of a scatter gather list may be a
+ byte offset encoded with a control field of 0x40 and followed
+ by a 3 byte binary offset (legal values 0-511). This offset
+ allows operations to beginning on any byte boundary
+ within the specified 512 byte block index.
+
+
+ The control field encoding 0xC0 indicates that the original
+ operation is conjoined with a second indexed operation
+ of the same direction starting at a new 512 byte block
+ index (as indicated in the following 7 bytes). The conjoined
+ index operation has its own scatter gather list optionally
+ starting with a byte offset, followed by one or more data
+ buffers.
+
+
+ Operation Modifiers:
+
+
+
+ 000: Base Operation
+
+
+
+ 001: Server Takeover Warning: informs the targeted
+ VASI server that another VASI server had previously
+ hosted the operation stream and that it may need to
+ perform additional steps to process this request.
+
+
+
+ 010 : 111 Reserved
+
+
+
+
+
+
+ VASI Operation Request Specifier structure
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI CRQ Message Definition (Normative)
+
+ For the VASI interface, all CRQ messages are defined to use the following base format:
+
+
+ General Form of VASI Reliable CRQ Element
+
+
+
+
+
+
+
+
+ Byte Offset
+
+
+
+
+ Field Name
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ 0
+
+
+ Header
+
+
+ Contains Element Valid Bit plus Event Type Encodings (
+ ).
+
+
+
+
+ 1
+
+
+ Format/Transport Event Code
+
+
+ For Valid Command Response Entries, see
+ .
+ For Transport Event Codes see
+ .
+
+
+
+
+ 2-15
+
+
+ Payload
+
+
+ Format dependent.
+
+
+
+
+
+
+
+ General format of a CRQ element
+
+
+
+
+
+
+
+
+
+
+
+
+ R1--1.
+
+ For the VASI option: The format byte of VASI
+ CRQ messages must be as defined in
+ .
+
+
+
+
+
+
+
+
+ R1--2.
+
+ For the VASI option: The status byte
+ of VASI CRQ response messages must be as defined in
+able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
+ .
+
+
+
+
+
+ VASI Reliable CRQ Response Status Values
+
+
+
+
+
+
+
+ Format Byte Value
+
+
+
+
+ Definition
+
+
+
+
+
+
+
+ 0x0
+
+
+ Success
+
+
+
+
+ 0x1
+
+
+ Hardware Error
+
+
+
+
+ 0x2
+
+
+ Invalid Stream ID
+
+
+
+
+ 0x3
+
+
+ Stream ID Abort
+
+
+
+
+ 0x4
+
+
+ Invalid Buffer Descriptor: Either the IOBA is too large for
+ the LIOBN or its logical TCE does not contain a valid
+ logical address mapping.
+
+
+
+
+ 0x5
+
+
+ Invalid buffer length: Either the buffer is less than the
+ minimum useful buffer size or it does not match one of the first
+ “ibm,#buffer-pools”
+ sizes that were added.
+
+
+
+
+ 0x6
+
+
+ Empty: The request could not be satisfied because the
+ buffer pool was empty
+
+
+
+
+ 0x7
+
+
+ Invalid VASI Download Request Specifier
+
+
+
+
+ 0x8
+
+
+ Invalid VASI Download data: The download data format is invalid.
+
+
+
+
+ 0x9
+
+
+ Invalid Buffer Correlator: Does not correspond to an
+ outstanding data buffer.
+
+
+
+
+ 0x0A
+
+
+ Invalid VASI Operation Request Specifier
+
+
+
+
+ 0x0B
+
+
+ Invalid Service Specifier
+
+
+
+
+ 0x0C
+
+
+ Too many opens
+
+
+
+
+ 0x0D
+
+
+ Invalid BOTTOM
+
+
+
+
+ 0x0E
+
+
+ Invalid TOP
+
+
+
+
+ 0x0F
+
+
+ End of File
+
+
+
+
+ 0x10
+
+
+ Invalid Format
+
+
+
+
+ 0x11
+
+
+ Unknown Reserved Value
+
+
+
+
+ 0x12
+
+
+ Invalid State Transition
+
+
+
+
+ 0x13
+
+
+ Race Lost
+
+
+
+
+ 0x14
+
+
+ Invalid Signal Code
+
+
+
+
+ 0x15-0xFF
+
+
+ Reserved
+
+
+
+
+
+
+
+
+ VASI Request/Response Pairs
+
+
+
+ R1--1.
+
+ For the VASI option:
+ The platform must validate the format byte in all VASI messages that it receives.
+
+
+
+
+ R1--2.
+
+ For the VASI option:
+ The platform must initiate the processing of VASI messages in the order received
+ on a given CRQ.
+
+
+
+
+ R1--3.
+
+ For the VASI option:
+ If the format byte value of a received VASI message, as specified in
+ ,
+ is “Unused”, “Reserved”, “VASI Operation Request”, or a response other
+ than “VASI Operation Response”, the platform must declare the format byte invalid.
+
+
+
+
+ R1--4.
+
+ For the VASI option:
+ If the format byte value is invalid, then the platform must generate a response
+ message on the corresponding CRQ by copying the received
+ message with the high order format byte bit set
+ to a one and the status byte with the “Invalid Format”
+ status code, and discard the received CRQ message.
+
+
+
+
+ R1--5.
+
+ For the VASI option:
+ The platform must fill in all reserved fields in VASI messages that it generates with zeros.
+
+
+
+
+ R1--6.
+
+ For the VASI option:
+ The platform must check that all reserved fields in a VASI message, except the
+ for the Capability String of the VASI Exchange Capabilities message, that it receives are filled with zeros,
+ else return the corresponding VASI reply message with a status of “Unknown Reserved Value”.
+
+
+
+
+ R1--7.
+
+ For the VASI option:
+ The VASI Exchange Capabilities message must be as defined in
+ .
+
+
+
+
+ R1--8.
+
+ For the VASI option:
+ The VASI Open message must be as defined in
+ .
+
+
+
+
+ R1--9.
+
+ For the VASI option:
+ The platform must process the VASI Open Request message per the semantics described in
+ .
+
+
+
+
+ R1--10.
+
+ For the VASI option:
+ The VASI Close message must be as defined in
+ .
+
+
+
+
+ R1--11.
+
+ For the VASI option:
+ The platform must process the VASI Close Request message per the semantics described in
+ .
+
+
+
+
+ R1--12.
+
+ For the VASI option:
+ The VASI Add Buffer message must be as defined in
+ .
+
+
+
+
+ R1--13.
+
+ For the VASI option:
+ The platform must process the VASI Add Buffer Request message per the semantics described in
+ .
+
+
+
+
+ R1--14.
+
+ For the VASI option:
+ The VASI Free Buffer message must be as defined in
+ .
+
+
+
+
+ R1--15.
+
+ For the VASI option:
+ The platform must process the VASI Free Buffer Request message per the semantics described in
+ .
+
+
+
+
+ R1--16.
+
+ For the VASI option:
+ The platform must process the VASI Download Request message per the semantics described in
+ .
+
+
+
+
+ R1--17.
+
+ For the VASI option:
+ The VASI Download message must be as defined in
+ .
+
+
+
+
+ R1--18.
+
+ For the VASI option:
+ The platform must process the VASI Operation Response message per the semantics described in
+ .
+
+
+
+
+ R1--19.
+
+ For the VASI option:
+ The VASI Operation message must be as defined in
+ .
+
+
+
+
+ R1--20.
+
+ For the VASI option:
+ The platform must process the VASI State Request message per the semantics described in
+ .
+
+
+
+
+ R1--21.
+
+ For the VASI option:
+ The VASI State message must be as defined in
+ .
+
+
+
+
+ R1--22.
+
+ For the VASI option:
+ The platform must process the VASI Progress Request message per the semantics described in
+ .
+
+
+
+
+ R1--23.
+
+ For the VASI option:
+ The VASI Progress message must be as defined in
+ .
+
+
+
+
+ R1--24.
+
+ For the VASI option:
+ The platform must process the VASI Signal Request message per the semantics described in
+ .
+
+
+
+
+ R1--25.
+
+ For the VASI option:
+ The VASI Signal message must be as defined in
+ .
+
+
+
+
+ R1--26.
+
+ For the VASI option:
+ To avoid a return code of “Invalid TOP” or “Invalid BOTTOM”; the VASI
+ messages: VASI Progress, VASI Add Buffer, VASI Free Buffer, VASI Download, VASI Operation, VASI Signal
+ and VASI State requests must only be sent after successful VASI Opens and prior to a VASI Close.
+
+
+
+
+
+ VASI Exchange Capabilities
+
+ The VASI Exchange Capabilities command response pair is used to negotiate run time characteristics of the VASI virtual
+ IOA. The using partition issues one VASI Exchange Capabilities request message for each service that it plans to
+ support, filling in the Capability String field of the exchange capabilities request (see
+ )
+ with the values that it plans to use for that service and enqueues the request. The VASI virtual
+ IOA copies to the response Capability String, the values from the request capability string that it can support. The Capability
+ string boolean fields are defined such that zero indicates that the characteristic is not supported. Capability
+ string fields that represent numeric values may be reduced by the VASI virtual IOA from the requested value to the
+ supported value with the numeric value zero being possible.
+ Status Values defined for the VASI Exchange Capabilities response message:
+
+
+
+ Success
+
+
+
+ Hardware
+
+
+
+
+ Format of the VASI Exchange Capabilities CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+ Capability String Fields
+
+
+
+
+
+
+
+
+ Field Name
+
+
+
+
+ Location (Byte:Bit - Byte:Bit)
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ Service
+
+
+ 3:0 - 3:7
+
+
+ Supported Services code see
+
+
+
+
+
+
+
+
+
+ Reserved 1
+
+
+ 4:1 - 13:5
+
+
+ Reserved for future expansion
+
+
+
+
+
+
+
+
+
+ Supported Download Forms
+
+
+ 13:6 Immediate
+ 13:7 Indirect
+
+
+ The forms of VASI Download that are supported. This is a bit
+ field so any combination is possible to represent. Immediate
+ and indirect refer to the buffer placement, either directly
+ following in the operation specifier or at a location specified by
+ an address.
+
+
+
+
+ Supported Operations
+
+
+ 14:0 Read Squential Immediate
+ 14:1 Read Sequential Indirect
+ 14:2 Read Indexed Immediate
+ 14:3 Read Indexed Indirect
+ 14:4 Write Sequential Immediate
+ 14:5 Write Sequential Indirect
+ 14:6 Write Indexed Immediate
+ 14:7 Write Indexed Indirect
+
+
+ The forms of VASI Operations that are supported. This is a bit
+ field so any combination is possible to represent. Sequential
+ and indexed refer to the starting point of the operation
+ (following the last operation or at a specific block offset).
+ Immediate and indirect refer to the buffer placement, either
+ directly following in the operation specifier or at a location
+ specified by an address.
+
+
+
+
+ #Opens
+
+
+ 15:0 - 15-7
+
+
+ Number of opens (unique TOP/BOTTOM pairs) per VASI
+ stream that are supported on this VASI Virtual IOA. Valid
+ values (1-255)
+
+
+
+
+
+
+
+
+
+ VASI Open
+
+ The VASI Open Command message, see
+ ,
+ indicates to the hypervisor that the originator VASI device driver is prepared to provide
+ the indicated processing service (role) for the indicated VASI stream.
+
+ The VASI Open Response message indicates to the originating VASI device driver that the hypervisor is prepared to
+ proceed with the indicated VASI stream.
+
+ Status Values defined for the VASI Open response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid Stream ID: The Stream ID parameter is not currently valid for this VASI virtual device.
+
+
+ Stream ID Aborted
+
+
+ Too many opens
+
+
+ Invalid Service Specifier: Either reserved value or service not defined for this VASI stream.
+
+
+
+
+ Semantics for VASI Open Request Message:
+
+ Construct VASI Open Response message prototype (Including service parameter from request).
+
+
+ Copy low order 8 bytes from Request message to response prototype.
+
+
+ Verify that the Stream ID parameter of the VASI Open Request message is valid for the caller, else respond with the
+ status of “Invalid Stream ID”.
+
+
+ Verify that the Service parameter of the VASI Open Request message is valid for the caller plus Stream ID pair, else
+ respond with the status of “Invalid Service Specifier”. Note that the valid “Service” values vary with the specific
+ high level function being performed (see
+ )
+ and the role assigned to the calling partition by mechanisms outside of the scope of PAPR.
+
+
+ If the state of the VASI stream specified by the Stream ID of a VASI Open Request message is “Aborted”, respond
+ with the status value of “Stream ID Aborted”.
+
+
+ If the maximum number of opens has not been reached, then allocate control structures to maintain the state of this
+ open instance and associate them with a unique BOTTOM parameter -- copy BOTTOM parameter to response message;
+ else respond with “Too many opens”.
+
+
+ Record the associated TOP parameter value for use in subsequent VASI response and operation request messages.
+
+
+ Respond with Success.
+
+
+
+
+ Format of the VASI Open CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Close
+
+ The VASI Close Command message, see
+ ,
+ requests the receiver to close the indicated BOTTOM instance of the VASI stream.
+ Note, other BOTTOM instances remain open.
+ The VASI Close Response message indicates that the VASI Close command receiver has processed the associated
+ VASI Close Command message and all previously enqueued messages to the BOTTOM instance. No further CRQ
+ messages will be enqueued by the closed BOTTOM service, and all enqueued buffers are forgotten.
+
+ Status Values defined for the VASI Close response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid BOTTOM
+
+
+
+
+ Semantics for VASI Close Request Message:
+
+ Construct VASI Close Response message prototype (copy low order 14 bytes from request message).
+
+
+ Validate the BOTTOM parameter is valid for caller, else respond “invalid BOTTOM”
+
+
+ Transition the service for the specified VASI stream instance to the “Closed” state -- This process ends after all previously
+ initiated VASI request messages for the BOTTOM instance have completed.
+
+
+ Insert the TOP recorded at open time for the specified BOTTOM into the response prototype.
+
+
+ Free queued buffers and deallocate the control structures associated with the BOTTOM parameter, then respond
+ Success.
+
+
+
+
+ Format of the VASI Close CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Add Buffer
+
+ The VASI Add Buffer Command message, see
+ ,
+ indicates to the hypervisor that the originator VSP device driver is providing the hypervisor with an empty
+ buffer for the specific BOTTOM instance.
+ The hypervisor organizes its input buffers into N buffer pools per service, by size as indicated by the buffer descriptor.
+ The VASI
+ “ibm,#buffer-pools”
+ device tree property relates how many buffer size pools the firmware implements.
+ The first N different sizes supplied by the device driver specifies the sizes of the N buffer size pools -- buffers of
+ other sizes are rejected.
+ The VASI Add Buffer Response message indicates to the originating VASI device driver that the hypervisor has processed
+ the associated VASI Add Buffer Command message. All VASI Add Buffer CRQ messages generate a VASI
+ Add Buffer Response message to provide feedback to the VASI device driver for flow control of the firmware's VASI
+ CRQ.
+ The successful Add Buffer Response CRQ message indicates the buffer size of the pool upon which the buffer was enqueued,
+ and the number of free buffers on the indicated buffer size pool after the add (to indicate buffer utilization).
+
+ Status Values defined for the VASI Add Buffer response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid BOTTOM
+
+
+ Invalid Buffer Descriptor
+
+
+ Invalid Buffer Length
+
+
+
+
+ Semantics for VASI Add Buffer Request Message:
+
+ Construct VASI Add Buffer Response message prototype (copy low order 14 bytes from the request message to the
+ response prototype).
+
+
+ Validate the BOTTOM field, else respond “Invalid BOTTOM”.
+
+
+ Insert the TOP recorded for the open BOTTOM into the response prototype.
+
+
+ Validate high order Buffer Descriptor bit is 0b1, else respond with “Invalid Buffer Descriptor”
+
+
+ Validate that the Buffer Descriptor address translates through the LIOBN of the first pane of the
+ “ibm,my-dma-window”
+ property, else respond with “Invalid Buffer Descriptor”.
+
+
+ Copy the first 8 bytes at the translated Buffer Descriptor address into the low order 8 bytes of the response prototype.
+
+
+ If the Buffer Descriptor length field does not match the buffer length of one of the buffer pools then:
+
+
+ If buffer lengths are assigned to all buffer pools, then respond with “Invalid Buffer Length”
+
+
+ Else select an unassigned buffer pool, and assign its length to match the length field of the Buffer Descriptor.
+
+
+
+
+
+ Enqueue the buffer descriptor onto the per service session (“BOTTOM”) pool whose buffer length matches the
+ length field of the Buffer Descriptor, increment the Free Buffers in Pool count for the pool; inserting the result into
+ the response prototype along with the buffer size, clear the reserved fields and respond with “Success”
+
+
+
+
+ Format of the VASI Add Buffer CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Free Buffer
+
+ The VASI Free Buffer Command message, see
+
+ requests the hypervisor to return an empty data buffer of the specified size to the originator VSP device
+ driver. This call is used to recover buffers. It may be used to recover buffers at the completion of a VASI operation
+ stream. All buffers added to a VASI virtual IOA service session (“BOTTOM”) are forgotten by the virtual IOA when
+ the service session is closed or the IOA’s CRQ is deregistered.
+ The VASI Free Buffer Response message indicates to the originating VASI device driver that the hypervisor has processed
+ the associated VASI Free Buffer Command message. All VASI Free Buffer CRQ messages generate a VASI
+ Free Buffer Response message. If the Status field of the VASI Free Buffer Response CRQ message is “Success” then
+ the last 8 bytes contain the Buffer Correlator (first 8 bytes of the data buffer) of the selected empty data buffer. The last
+ 8 bytes of the VASI Free Buffer Response CRQ message are undefined for any non “Success” Status value.
+
+
+ Status Values defined for the VASI Free Buffer response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid BOTTOM
+
+
+ Invalid Buffer Length
+
+
+ Empty
+
+
+
+
+ Semantics for VASI Free Buffer Request Message:
+
+ Construct VASI Free Buffer Response message prototype with the Buffer Correlator field zero.
+
+
+ Validate the BOTTOM field, else respond “Invalid BOTTOM”.
+
+
+ Insert the TOP recorded for the open BOTTOM into the response prototype.
+
+
+ If the request message Buffer Length field does not match one of the pool lengths, then respond “Invalid Buffer
+ Length”.
+
+
+ If the buffer pool associated with the Buffer Length field is empty, then respond “Empty”.
+
+
+ Dequeue a Buffer Descriptor from the buffer pool associated with the Buffer Length field.
+
+
+ Copy the first 8 bytes at the translated Buffer Descriptor address into the low order 8 bytes of the response prototype
+ and respond “Success”.
+
+
+
+
+ Format of the VASI Free Buffer CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Download
+
+ The VASI Download Command message, see
+
+ requests the hypervisor to process the VASI Download data buffer specified by the
+ originator VSP device driver.
+
+ The VASI Download Response message indicates to the originating VSP that the hypervisor has processed the associated
+ VASI Download Command message. Unless the Status field of the VASI Download Response CRQ message is
+ “Invalid Buffer Descriptor”, the last 8 bytes contain the Buffer Correlator (first 8 bytes of the data buffer) of the data
+ buffer specified by the Buffer Descriptor field of the VASI Download Command CRQ message. The last 8 bytes of the
+ VASI Download Response CRQ message are undefined for the “Invalid Buffer Descriptor” Status value.
+
+ Status Values defined for the VASI Download response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid BOTTOM
+
+
+ Invalid Buffer Descriptor
+
+
+ Invalid VASI Download Request Specifier
+
+
+ Invalid VASI Download data
+
+
+
+
+ Semantics for VASI Download Request Message:
+
+ Construct VASI Download Response message prototype (copy low order 14 bytes from Request message to response
+ prototype).
+
+
+ Validate the BOTTOM field, else respond “Invalid BOTTOM”.
+
+
+ Insert the TOP recorded for the open BOTTOM into the response prototype.
+
+
+ Validate high order Buffer Descriptor bit is 0b1, else respond with “Invalid Buffer Descriptor”
+
+
+ Validate that the Buffer Descriptor address translates through the LIOBN of the first pane of the
+ “ibm,my-dma-window”
+ property, else respond with “Invalid Buffer Descriptor”.
+
+
+ Copy the first 8 bytes at the translated Buffer Descriptor address into the low order 8 bytes of the response prototype.
+
+
+ Verify that the BOTTOM parameter of the buffer’s VASI Download Request Specifier is valid for the caller and the
+ Download service for the associated Stream ID is Open by the caller, else respond with “Invalid VASI Download
+ Request Specifier”.
+
+
+ The Download service processes the buffer data; if an error is detected in the buffer data respond with “Invalid VASI
+ Download data”, else respond with “Success”.
+
+
+
+
+ Format of the VASI Download CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Operation
+
+ The VASI Operation Request message, see Figure 47‚ “Format of the VASI Operation CRQ elements‚” on page 731,
+ requests the receiving VSP to process the VASI Operation specified in the data buffer indicated by the Buffer Correlator
+ field. The Buffer Correlator field is copied from the first 8 bytes of the data buffer as supplied by the VSP using the
+ VASI add buffer request. VASI Operation Requests are used to upload data on migration/hibernation (Write Sequential)
+ and for VPM paging requests (using indexed Read/Write).
+ The VASI Operation Response message indicates to the hypervisor that the VSP has processed the associated VASI
+ Operation Command message. Unless the Status field of the VASI Operation Response CRQ message is “Invalid
+ Buffer Correlator”, the last 8 bytes contain the Operation Correlator (fourth 8 bytes of the data buffer) of the data buffer
+ that the hypervisor selected for this operation. The last 8 bytes of the VASI Operation Response CRQ message are undefined
+ for the “Invalid Buffer Correlator” Status value. The VSP validates that the TOP parameter corresponds to an
+ open instance against a VASI stream ID, else it responds “Invalid TOP”. Similarly the VSP validates the format of the
+ remainder of the buffer, else responds “Invalid VASI Operation Request Specifier”.
+
+ Status Values defined for the VASI Operation response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid Buffer Correlator
+
+
+ Invalid TOP
+
+
+ Invalid VASI Operation Request Specifier
+
+
+ Stream ID Aborted
+
+
+ End of File
+
+
+
+
+ Semantics for VASI Operation Response Message:
+
+ Verify that the Operation Correlator references a valid outstanding VASI Operation, else discard message.
+ NOTE: while an invalid operation correlator is a very serious error there is no obvious instance to which to deliver the
+ error.
+
+
+ Mark the operation control block as referenced by the Operation Correlator with the Status and Residual values, refer
+ to , from the Response message and mark the
+ response message as being processed.
+
+
+ Further processing of the operation control block is covered in the specification for the specific VASI Operation
+ Stream. See .
+
+
+
+
+ Format of the VASI Operation CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Signal
+
+ The VASI Signal Command message (See
+ )
+ informs the VASI Virtual IOA of the VASI Stream, associated with the BOTTOM parameter, of the condition specified
+ by the “Signal Code” parameter; optionally, a non-zero reason code may be associated with the event so that firmware
+ may record the event using facilities and methods that are outside the scope of this architecture.
+ The valid signal codes, and reason codes are unique to the specific VASI operation stream. See
+ and
+
+ respectively for more details.
+
+ Status Values defined for the VASI State response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid BOTTOM
+
+
+ Invalid Signal Code
+
+
+
+
+ Semantics for processing the VASI Signal Request Message:
+
+ Construct VASI Signal Response message prototype (copy the low order 14 bytes from the Request message to the
+ response prototype).
+
+
+ Validate the BOTTOM parameter for the caller; else respond “Invalid BOTTOM”
+
+
+ Insert the TOP recorded for the open BOTTOM into the response prototype.
+
+
+ Determine the VASI stream associated with the BOTTOM parameter.
+
+
+ If the “Signal” parameter represents an invalid signal
+ code for the VASI operation stream represented by the BOTTOM parameter (refer to
+ ),
+ then respond “Invalid Signal Code”.
+
+
+ Initiate the VASI stream event processing for the VASI operation
+ stream represented by the BOTTOM parameter as defined under
+
+ for the current state and the condition represented by the “Signal”
+ parameter, record the value of the “Reason” parameter, and respond “Success”.
+
+
+
+
+ Format of the VASI Signal CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI State
+
+ The VASI virtual IOA generates a VASI State Request message, see
+ ,
+ to each VASI open session instance (TOP), that is associated (through a VASI Open) with the
+ VASI Stream ID, each time the VASI stream changes state. Such state change request messages may include an optional
+ non-zero reason code.
+ No VASI State Response message is defined. The VASI State Request message is informational, and the receiver does
+ not generate a response.
+
+ The valid states, state transitions, and reason codes are unique to the specific VASI operation stream, see
+ .
+
+
+ Semantics for VASI State Request Message sent only after all other VASI stream state transition processing completes:
+
+ For each TOP opened for the VASI stream that changed state.
+
+
+ Construct VASI State Request message prototype.
+
+
+ Fill in the TOP from the values recorded at VASI open time.
+
+
+ Fill in the “Reason” and “To” fields per the completed transition.
+
+
+ Enqueue the request message to the CRQ used to open the associated TOP.
+
+
+
+
+
+ Mark the VASI stream state transition complete.
+
+
+
+
+ Format of the VASI State CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Progress
+
+ The VASI Progress Command message, see
+ ,
+ is applicable to Migration and Hibernation high level operations. It requests the hypervisor to report the number of bytes
+ of partition state that need to be processed for the VASI migration/hibernation stream associated with the “BOTTOM”
+ parameter. If this request is made prior to any state transfer requests, it represents the total size of the partition state
+ data.
+
+ If the Status field of the VASI Progress Response CRQ message is “Invalid BOTTOM”, the last 8 bytes of the VASI
+ Progress Response CRQ message are copied from the corresponding VASI Progress Request message in all cases.
+
+ Status Values defined for the VASI State response message:
+
+
+
+ Success
+
+
+ Hardware
+
+
+ Invalid BOTTOM
+
+
+ Invalid Service Specifier
+
+
+
+
+ Semantics for VASI Progress Request Message:
+
+ Construct VASI Progress Response message prototype (copy the low order 14 bytes from Request message to response
+ prototype).
+
+
+ Validate the BOTTOM parameter for the caller, else respond “invalid BOTTOM”
+
+
+ Insert the TOP recorded for the open BOTTOM into the response prototype.
+
+
+ Validate that the operation stream associated with the BOTTOM parameter is either a migration or a hibernation;
+ else respond “Invalid Service Specifier”.
+
+
+ Estimate the number of bytes left to transfer (this is best effort since the number may constantly change) placing the
+ value into the “Number of Bytes Left” field and respond Success.
+
+
+ For the source side of an operation the estimate of the number of bytes left is the number of bytes of dirty status.
+
+
+ For the destination side of an operation the estimate of the number of bytes left is the number of expected status
+ bytes that the destination knows are not valid (either they were never sent or there has been an indication that they
+ were subsequently made invalid).
+
+
+
+
+
+
+
+ Format of the VASI Progress CRQ elements
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ VASI Virtual IOA Device Tree
+
+
+ Properties of the VASI Node in a Partition
+
+
+
+
+
+
+
+
+ Property Name
+
+
+
+
+ Required?
+
+
+
+
+ Definition
+
+
+
+
+
+
+
+ “name”
+
+
+ Y
+
+
+ IBM,VASI
+
+
+
+
+ “device_type”
+
+
+ Y
+
+
+ IBM,VASI-1
+
+
+
+
+ “model”
+
+
+ NA
+
+
+ Property not present.
+
+
+
+
+ “compatible”
+
+
+ Y
+
+
+ IBM,VASI-1
+
+
+
+
+ “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 of length
+ “#address-cells”
+ value shall be 0xwhatever (virtual
+ “reg”
+ property used for unit address no actual locations used, therefore, the size field
+ has zero cells (does not exist) as determined by the value of the
+ “#size-cells” property).
+
+
+
+
+ “ibm,my-dma-window”
+
+
+ Y
+
+
+ Property name specifying the DMA window
+ associated with this virtual IOA presented as an encoded
+ array of tripples; each triple consisting 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”
+
+
+ N
+
+
+ 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. If the
+ “ibm,#dma-size-cells”
+ property is missing, the default value is the
+ “#size-cells”
+ property for the parent package.
+
+
+
+
+ “ibm,#dma-address-cells”
+
+
+ N
+
+
+ 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
+ child's dma-window properties. If the
+ “ibm,#dma-address-cells”
+ property is missing, the default value is the
+ “#address-cells”
+ property for the parent package.
+
+
+
+
+ “ibm,#buffer-pools”
+
+
+ Y
+
+
+ Property name to define number, encoded as with
+ encode-int
+ of different data buffer size pools
+ supported by the VASI virtual IOA service sessions.
+
+
+
+
+ “ibm,crq-size”
+
+
+ Y
+
+
+ Property name to define the size, in bytes, of the VASI virtual IOA CRQ; encoded as with
+ encode-int.
+
+
+
+
+ “ibm,#vasi-streams”
+
+
+ Y
+
+
+ Property name to define the number of simultaneous
+ unique VASI stream IDs that may be supported by
+ the VASI virtual IOA CRQ; encoded as with
+ encode-int.
+
+
+
+
+
+
+
+
+
+ VASI Support hcall()s
+
+ The hcall()s of this section support the VASI option. H_DONOR_OPERATION supplies the hypervisor with processor
+ cycles to perform administrative services. H_VASI_SIGNAL allows partitions to signal anomalous conditions such as
+ the need to abort the administrative service stream without having to have an open VASI virtual IOA. While the
+ H_VASI_STATE allows partitions that do not have an open VASI virtual IOA for a given VASI stream ID to poll the
+ state of their administrative service streams.
+
+
+ H_DONOR_OPERATION
+
+ This hcall() supplies donor partition cycles to perform hypervisor operations for a given VASI Stream. The TOP/BOTTOM
+ parameter indicates the VASI stream, and thus a specific operating context relative to the caller and callee. The
+ cycles donated by any and all TOP/BOTTOMs associated with the VASI Stream are combined by the platform to perform
+ the needed processing for the stream. A platform may use the cycles from different TOP/BOTTOM pairs to create
+ parallel processes to improve the stream performance.
+
+
+ Syntax:
+
+
+
+
+
+
+ Parameters:
+
+
+
+ TOP/BOTTOM_ID (The opaque handles of a specific VASI operation stream relative to the caller and callee.)
+
+
+
+
+
+ Semantics:
+
+
+
+ If the TOP/BOTTOM_ID parameter is invalid relative to the calling partition, return H_Parameter.
+
+
+ If the VASI stream is in the aborted state, return H_Aborted.
+
+
+ Perform the next operation associated with the specified VASI stream. Note the amount of processing performed on
+ any one call is limited by the interrupt hold off constraints of standard hypervisor calls. (The format of the platform
+ operation state structure is outside of the scope of this architecture.)
+
+
+ If the specific VASI stream operation is fully complete, return H_Success.
+
+
+ If the specific VASI stream requires more processing to fully complete the platform operation and is not blocked
+ waiting for asynchronous agent(s), return H_IN_PROGRESS.
+
+
+ If the VASI stream is blocked waiting for asynchronous agent(s), return H_LongBusyOrder* (where * is the appropriate
+ expected waiting time).
+
+
+
+
+
+ R1--1.
+
+ For the VASI option:
+ The platform must implement the H_DONOR_OPERATION hcall() following
+ the syntax and semantics of
+ .
+
+
+
+
+
+
+
+
+ H_VASI_SIGNAL
+
+ This hcall() signals the condition specified by the “signal code”
+ parameter to the VASI Virtual IOA of the VASI Stream
+ associated with the “handle” parameter; optionally, a non-zero
+ “reason code” may be associated with the signal code so
+ that firmware may record the signal using facilities and methods
+ that are outside the scope of this architecture.
+
+
+ Syntax:
+
+
+
+
+
+ Parameters:
+
+
+
+ handle -- the VASI Stream ID (The opaque handle of a specific VASI operation stream.)
+
+
+ signal_code -- one of the values listed in
+
+ right justified with high order bytes zero.
+
+
+ reason_code -- Code user gives as reason for signal right
+ justified with high order bytes zero -- The value is simply
+ transported not checked by the platform.
+
+
+
+
+
+ Semantics:
+
+
+
+ If the “handle” parameter is invalid relative to the calling partition, then return H_Parameter.
+
+
+ If the “signal_code” is invalid based upon the values listed in
+ ,
+ then return H_P2.
+
+
+ If the “signal_code” is valid for the current VASI stream state,
+ initiate the processing defined for the “signal_code”;
+ else return H_NOOP.
+
+
+
+
+ VASI Signal Codes
+
+
+
+
+
+
+
+
+
+
+
+ Name
+
+
+
+
+ Value
+
+
+
+
+ Description
+
+
+
+
+ VASI Operation Stream
+
+
+
+
+ Valid for Interface
+
+
+
+
+
+
+ VASI Signal Message
+
+
+
+
+ H_VASI_SIGNAL
+
+
+
+
+
+
+
+ Null
+
+
+ 0x0
+
+
+ Not used (invalid)
+
+
+ All
+
+
+ N
+
+
+ N
+
+
+
+
+ Cancel
+
+
+ 0x1
+
+
+ Gracefully cancel processing if possible
+
+
+ Partition MigrationPartition Hibernation
+
+
+ Y
+
+
+ Y
+
+
+
+
+ Abort
+
+
+ 0x2
+
+
+ Immediately halt function
+
+
+ Partition MigrationPartition Hibernation
+
+
+ Y
+
+
+ N
+
+
+
+
+ Suspend
+
+
+ 0x3
+
+
+ Suspend target partition
+
+
+ Partition MigrationPartition Hibernation
+
+
+ Y
+
+
+ N
+
+
+
+
+ Complete
+
+
+ 0x4
+
+
+ Complete paging operation
+
+
+ Paging
+
+
+ Y
+
+
+ N
+
+
+
+
+ Enable
+
+
+ 0x5
+
+
+ Enabling paging operation
+
+
+ Paging
+
+
+ Y
+
+
+ N
+
+
+
+
+ Reserved
+
+
+ 0x6-0xFFFF
+
+
+ Reserved
+
+
+ All
+
+
+ N
+
+
+ N
+
+
+
+
+
+
+
+
+ R1--1.
+
+ For the VASI option:
+ The platform must implement the H_VASI_SIGNAL hcall() following the syntax and semantics of
+ .
+
+
+
+
+
+
+
+
+ H_VASI_STATE
+
+ This hcall() returns the state of the specific VASI operation stream.
+
+
+ Syntax:
+
+
+
+
+
+
+ Parameters:
+
+
+
+ handle -- the VASI Stream ID (The opaque handle of a specific VASI operation stream relative to the caller and callee.)
+
+
+
+
+
+ Semantics:
+
+
+
+ If the “handle” parameter is invalid relative to the calling partition, return H_Parameter.
+
+
+ Else enter the value of the VASI state variable (see
+ )
+ for the indicated stream into R4 and return H_Success
+
+
+
+
+
+ R1--1.
+
+ For the VASI option:
+ The platform must implement the H_VASI_STATE hcall() following the syntax and semantics of
+ .
+
+
+
+
+
+
+
+
+ VASI Operation Stream Specifications
+
+ This section defines the usage of VASI to accomplish specific administrative services. Each section specifies the valid
+ VASI state codes, state transitions, and reason codes, the action of the VASI virtual IOA in each state and the expected
+ behavior of the VASI device driver in order to achieve the operational goal.
+
+
+ VASI Stream Services for Partition Migration
+
+
+
+
+
+
+
+
+ Name
+
+
+
+
+ Value
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ Unused
+
+
+ 0
+
+
+
+
+
+
+
+ Source Mover for Partition Migration
+
+
+ 1
+
+
+ VASI device will be used to extract partition state from the source platform to the target
+ platform using VASI Operations (Write sequential) to extract partition state, and VASI
+ Download commands to give source platform paging requests. See
+ .
+
+
+
+
+ Target Mover for Partition Migration
+
+
+ 2
+
+
+ VASI device will be used to insert migrating partition’s state to the target platform. VASI
+ Download requests will be used to give platform firmware partition state, and VASI
+ Operations (Write sequential) will be used by platform firmware to give paging requests to
+ the Mover partition to deliver to the source platform.See
+ .
+
+
+
+
+ Pager for the CMO option
+
+
+ 3
+
+
+ VASI device will be used to handle CMO paging requests See
+ .
+
+
+
+
+
+
+
+
+ Partition Migration
+
+
+ defines the VASI Services for Partition Migration for use in the VASI Open CRQ request, as defined in
+ .
+
+ Requirements:
+
+
+
+ R1--1.
+
+ For the Partition Migration Option:
+ If any partition code uses the value of the processor PVR to modify its operation, to ensure
+ valid operation after the resume from suspension, prior to executing any such
+ modified operation code, partition code must reread the PVR value and be prepared to remodify its operation.
+
+
+
+
+ R1--2.
+
+ For the Partition Migration Option:
+ In order that LAN communication partners may learn of the
+ new MAC address that may be associated with a migrated partition, the migrated partition must generate
+ “gratuitous ARP” messages. It is suggested that these “gratuitous ARP” messages be sent at the rate of once
+ per second between the time that the migrating partition resumes and the H_VASI_STATE hcall() responds
+ with “Completed”.
+
+
+
+
+ R1--3.
+
+ For the Partition Migration Option:
+ To maintain the platform capability to perform live firmware
+ updates, the OS must call the
+ ibm,activate-firmware RTAS service after waking from a migration suspension.
+
+
+
+
+ R1--4.
+
+ For the Partition Migration Option:
+ The platform must implement the ILLAN option (see
+ ).
+
+
+
+
+ R1--5.
+
+ For the Partition Migration Option:
+ Platform firmware must support both immediate and indirect
+ data in its VASI Download data buffers.
+
+
+
+
+ R1--6.
+
+ For the Partition Migration Option:
+ If multiple partition migrations are being performed using a
+ single VASI device, to ensure none of the migrations are starved, partition software must call
+ H_DONOR_OPERATION with TOP/BOTTOMs associated with each migration (VASI Stream ID).
+
+
+
+
+ R1--7.
+
+ For the Partition Migration Option:
+ If the platform detects any unrecoverable error in processing
+ a VASI Download command, it must transition the associated VASI stream to the “Aborted” state.
+
+
+
+
+ R1--8.
+
+ For the Partition Migration Option:
+ The VASI stream ID for the specific high level migration
+ function must be the same value in both the source and target platforms.
+
+
+
+
+ Programming Note:
+ If partition software wishes to get an accurate count of the number of bytes to be transferred using
+ the VASI Progress CRQ message, it should be issued immediately following a VASI open and before any cycles
+ are donated for that migration via H_DONOR_OPERATION.
+
+
+ Partition Migration Abort Reason Codes
+
+
+ defines the Abort reason code layout for Partition Migration for use with the
+ H_VASI_SIGNAL hypervisor call and the VASI Signal and State CRQ requests, as defined in
+ .
+
+
+ Partition Migration Abort Reason Codes
+
+
+
+
+
+
+
+
+ Name
+
+
+
+
+ Byte
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ Aborting Entity
+
+
+ 0
+
+
+ 1=Orchestrator
+ 2=VSP providing VASI partition source migration service
+ 3=Partition Firmware
+ 4=Platform Firmware
+ 5=VSP providing VASI partition target migration service
+ 6=Migrating partition
+
+
+
+
+ Detailed Error
+
+
+ 1-3
+
+
+ Bytes one through three of the reason code are opaque values, architected by
+ individual aborting entities.
+
+
+
+
+
+
+
+
+ Partition Migration VASI States
+
+ This section defines the partition migration VASI states as used in the VASI State request CRQ message and as returned
+ from the H_VASI_STATE hcall.
+
+
+ VASI Migration Session States
+
+
+
+
+
+
+
+
+ Name
+
+
+
+
+ Value
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ Invalid
+
+
+ 0x0
+
+
+ This state is defined on both the source and destination platform
+ and indicates either that the specified Stream ID is not valid (or
+ is no longer valid) or the invoking partition is not authorized to
+ utilize the Stream ID.
+
+
+
+
+ Enabled
+
+
+ 1
+
+
+ This state is defined on both the source and destination platform
+ and indicates that the partition has been enabled for migration
+ but has not progressed beyond this initial state.
+ The transition to this state is triggered by events outside of the
+ scope of PAPR.
+ The partition on the source server transitions to this state first
+ and then the partition on the destination server.
+
+
+
+
+ Aborted
+
+
+ 2
+
+
+ This state is defined on both the source and the destination
+ platform and indicates that the abort processing has completed.
+ If the migration has been aborted, this is the final state of the
+ migration and platform firmware ensures that all interested
+ partitions see this state at least once. Platform firmware
+ continues to return this state until events outside of the scope of
+ PAPR terminate the operation and all interested partitions have
+ seen this final state.
+ In this state VASI download request information is flushed,
+ returning success status. VASI signal requests other than
+ “abort” are treated as an invalid state transition.
+ The transition to this state occurs on the two servers
+ independently and thus it is a race condition which server
+ transitions to this state first.
+
+
+
+
+ Suspending
+
+
+ 3
+
+
+ This state is defined only on the source platform and indicates
+ that the partition is in the process of suspending itself. When the
+ migrating partition sees this state, it enters its suspension
+ sequence that concludes with the call to ibm,suspend-me.
+ The transition to this state occurs when the source VSP directs
+ platform firmware to suspend the partition via a VASI Signal
+ request (Signal Code = Suspend) on the VASI device.
+
+
+
+
+ Suspended
+
+
+ 4
+
+
+ This state is defined only on the source platform and indicates
+ that the partition has suspended itself via the ibm,suspend-me
+ RTAS call. This is the point in the sequence where platform
+ firmware will reject attempts by the user to abort the migration.
+
+
+
+
+ Resumed
+
+
+ 5
+
+
+ This state is defined on both the source and destination platform
+ and indicates that the partition has resumed execution on the
+ destination platform.
+ The transition to this state occurs on the destination platform
+ first when it receives the dirty page bitmap from the source
+ platform firmware. It is at this point the virtual processors of the
+ migrating partition are dispatched on the destination platform.
+
+
+
+
+ Completed
+
+
+ 6
+
+
+ This state is defined on both the source and destination platform
+ and indicates that the migration has completed and all partition
+ state has been transferred to the destination platform. This is the
+ final state of the migration and platform firmware ensures that
+ all interested partitions see this state at least once. Platform
+ firmware continues to return this state until events outside of the
+ scope of PAPR terminate the operation and all interested
+ partitions have seen this final state.
+ The transition to this state occurs on the source platform first as
+ soon as all of the residual state of the migrating partition has
+ been successfully transferred to the destination platform. The
+ transition to this state on the destination platform occurs when
+ all of the partition state has been received from the source
+ platform.
+ For an inactive migration, the partition is transferred as a single
+ unit so the partition in the destination platform just moves from
+ Enabled to Completed on a successful inactive migration.
+
+
+
+
+
+
+
+
+
+
+
+ Partition Hibernation
+
+
+
+ R1--1.
+
+ For the Partition Hibernation Option:
+ The platform must ensure that all hibernating partition dynamic
+ reconfiguration operations are complete prior to signaling suspension of the partition.
+
+
+
+
+ R1--2.
+
+ For the Partition Hibernation Option:
+ If any partition code uses the value of the processor PVR
+ to modify its operation, after the resume from suspension, but prior to executing any such modified operation
+ code, it must reread the PVR value and be prepared to remodify its operation.
+
+
+
+
+ R1--3.
+
+ For the Partition Hibernation Option:
+ In order that LAN communication partners may learn of
+ the new MAC address that may be associated with a hibernated partition the hibernated partition must generate
+ “gratuitous ARP” messages. It is suggested that these “gratuitous ARP” messages be sent at the rate of
+ once per second between the time that the hibernated partition resumes and the H_VASI_STATE hcall() responds
+ with “Completed”.
+
+
+
+
+ R1--4.
+
+ For the Partition Hibernation Option:
+ To maintain the platform capability to perform live firmware
+ updates, the OS must call the ibm,activate-firmware
+ RTAS service after waking from a hibernation suspension.
+
+
+
+
+ R1--5.
+
+ For the Partition Hibernation Option:
+ The platform must implement the ILLAN option (see
+ ).
+
+
+
+
+ R1--6.
+
+ For the Partition Hibernation Option:
+ The VASI stream ID for the specific high level migration
+ function must be the same value for both the suspend and wake phases.
+
+
+
+
+
+
+
+ Cooperative Memory Overcommitment
+
+ The CMO option defines the stream service value 3 for “Pager”. The Pager VASI device is used to page out paging partition
+ state to the VASI Server Partition (VSP) using VASI Operation requests (Write indexed) and also to page in partition
+ state from the VSP using VASI Operation requests (Read indexed). The Pager VASI service utilizes a subset of
+ the VASI Operation request architecture; specifically in the VASI Operation Request Specifier structure, the File offset
+ of the start for indexed operations field (Bytes 9:15) is not used (value = 0x00); the scatter/gather list is a series of 1 –
+ N sub operation specifications each starting with the positioning of the file cursor using a type 0xC0 control element to
+ establish the file block location, optionally followed by a type 0x40 control element to position the file cursor to a byte
+ within the established file block, this is followed by one and only one type 0x80 control element per sub operation to
+ transfer the sub operation data. The VASI Operation Request Specifier structure terminates as always with a type 0x00
+ control element with a segment length field of 0x000000.
+
+ When a Pager VASI service aborts, the reason code returned is per
+ .
+ The Pager Service VASI States as in the state request CRQ message and as returned from the
+ H_VASI_STATE hcall are as defined in
+ .
+
+
+ CMO VASI Abort Reason Codes
+
+
+
+
+
+
+
+
+ Name
+
+
+
+
+ Byte
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ Entity (who is issuing state change or signal)
+
+
+ 0
+
+
+ 1 = VASI
+ 2 = I/O Provider
+ 3 = Platform Firmware
+
+
+
+
+ Detailed Reason
+
+
+ 1-3
+
+
+ Bytes one through three of the reason code are opaque values, architected by individual entities.
+
+
+
+
+
+
+
+ CMO VASI States
+
+
+
+
+
+
+
+
+ Name
+
+
+
+
+ Value
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ Invalid
+
+
+ 0x0
+
+
+ This state indicates that the specified Stream ID is not valid (or is no longer valid) or the invoking
+ partition is not authorized to utilize the Stream ID.
+
+
+
+
+ Disabled
+
+
+ 1
+
+
+ This state indicates that the specified Stream ID is valid, but the stream has not been yet opened
+ by the VSP providing VASI paging service. The transition to this state is triggered by events
+ outside of the scope of PAPR.
+
+
+
+
+ Suspended
+
+
+ 2
+
+
+ This state indicates that the specified Stream ID is valid, but the client partition has not yet been
+ powered on
+
+
+
+
+ Enabled
+
+
+ 3
+
+
+ This state indicates that the stream has been opened by the VSP providing VASI paging service
+ and the client partition is powered on
+
+
+
+
+ Stopped
+
+
+ 4
+
+
+ This state indicates that the specified Stream ID is valid, however platform firmware is no longer
+ using the stream to perform paging. The transition to this state is triggered by events outside of the
+ scope of PAPR.
+
+
+
+
+ Completed
+
+
+ 5
+
+
+ This state indicates that paging has been terminated for this stream by a request to halt paging for
+ this Stream ID.
+
+
+
+
+
+
+
+
+
Virtual Fibre Channel (VFC) using NPIVN_Port ID Virtualization (NPIV) is part of the Fibre Channel (FC)
diff --git a/Virtualization/figures/figure_format_vasi_add_buffer_crq_elem.gif b/Virtualization/figures/figure_format_vasi_add_buffer_crq_elem.gif
new file mode 100644
index 0000000..a82ba67
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_add_buffer_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_close_crq_elem.gif b/Virtualization/figures/figure_format_vasi_close_crq_elem.gif
new file mode 100644
index 0000000..8db7d3f
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_close_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_download_crq_elem.gif b/Virtualization/figures/figure_format_vasi_download_crq_elem.gif
new file mode 100644
index 0000000..5cbcf94
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_download_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_exchange_cap_crq_elem.gif b/Virtualization/figures/figure_format_vasi_exchange_cap_crq_elem.gif
new file mode 100644
index 0000000..9580aff
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_exchange_cap_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_free_buffer_crq_elem.gif b/Virtualization/figures/figure_format_vasi_free_buffer_crq_elem.gif
new file mode 100644
index 0000000..b9f5f63
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_free_buffer_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_open_crq_elem.gif b/Virtualization/figures/figure_format_vasi_open_crq_elem.gif
new file mode 100644
index 0000000..d0e7042
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_open_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_operation_crq_elem.gif b/Virtualization/figures/figure_format_vasi_operation_crq_elem.gif
new file mode 100644
index 0000000..a4f5391
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_operation_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_progress_crq_elem.gif b/Virtualization/figures/figure_format_vasi_progress_crq_elem.gif
new file mode 100644
index 0000000..4eae8d6
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_progress_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_signal_crq_elem.gif b/Virtualization/figures/figure_format_vasi_signal_crq_elem.gif
new file mode 100644
index 0000000..019f5c0
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_signal_crq_elem.gif differ
diff --git a/Virtualization/figures/figure_format_vasi_state_crq_elem.gif b/Virtualization/figures/figure_format_vasi_state_crq_elem.gif
new file mode 100644
index 0000000..c8ab258
Binary files /dev/null and b/Virtualization/figures/figure_format_vasi_state_crq_elem.gif differ
diff --git a/Virtualization/figures/general_format_crq_element.gif b/Virtualization/figures/general_format_crq_element.gif
new file mode 100644
index 0000000..7002268
Binary files /dev/null and b/Virtualization/figures/general_format_crq_element.gif differ
diff --git a/Virtualization/figures/vasi_download_request_specifier.gif b/Virtualization/figures/vasi_download_request_specifier.gif
new file mode 100644
index 0000000..6e4537f
Binary files /dev/null and b/Virtualization/figures/vasi_download_request_specifier.gif differ
diff --git a/Virtualization/figures/vasi_operation_request_specifier.gif b/Virtualization/figures/vasi_operation_request_specifier.gif
new file mode 100644
index 0000000..418532f
Binary files /dev/null and b/Virtualization/figures/vasi_operation_request_specifier.gif differ