From 51d830d91289a92b29912e3577eba32bb478213c Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Mon, 6 Apr 2020 16:58:53 -0500 Subject: [PATCH] Add H_VIOCTL subfunctions for VNIC failover support Signed-off-by: Jeff Scheel --- Virtualization/ch_virtual_io.xml | 4848 ++++++++++++++++-------------- 1 file changed, 2599 insertions(+), 2249 deletions(-) diff --git a/Virtualization/ch_virtual_io.xml b/Virtualization/ch_virtual_io.xml index a6a20b3..78c9fcc 100644 --- a/Virtualization/ch_virtual_io.xml +++ b/Virtualization/ch_virtual_io.xml @@ -6,24 +6,24 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo appearance of I/O adapters that do not have a one to one correspondence with a physical IOA. The hypervisor uses one of three techniques to realize a virtual IOA: - - + + In the hypervisor simulated class, the hypervisor may totally simulate the adapter. For example, this is used in the virtual ethernet (IEEE - VLAN) support (see + VLAN) support (see ). This technique is applicable to communications between partitions that are created by a single hypervisor instance. - In the - partition managed class, a + In the + partition managed class, a server partition provides the services of one of its - IOA’s to a - partner partition(s) (one or more + IOA’s to a + partner partition(s) (one or more client partitions The term “hosted” is sometimes used for “client” and the term “hosting” is sometimes used @@ -36,21 +36,21 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo interpret I/O requests from the partner partition, perform those requests on one or more of its devices, targeting the partner partition’s DMA buffer areas (for example, by using the Remote DMA (RDMA) facilities), and - passing I/O responses back to the partner partition. For example, see + passing I/O responses back to the partner partition. For example, see . - In the + In the hypervisor managed class, the hypervisor may provide low level hardware management (error and sub-channel allocation) so that partition level code may directly manage its assigned sub-channels. - - - + + + This chapter is organized from general to specific. The overall - structure of this architecture is as shown in + structure of this architecture is as shown in .
@@ -69,10 +69,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
Terminology used with VIO - Besides the general terminology defined on the first page of this + Besides the general terminology defined on the first page of this chapter, will assist the reader in understanding the content of this chapter. - + Terminology used with VIO @@ -106,7 +106,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Interpartition Logical LAN. This option uses the hypervisor simulated class of virtual I/O to provide partition-to-partition LAN facilities without a real LAN IOA. - See + See . @@ -116,7 +116,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Virtual SCSI. This option provides the facilities for - sharing physical SCSI type IOAs between partitions. + sharing physical SCSI type IOAs between partitions. . @@ -136,11 +136,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo server and client partition, but under different virtual IOAs. The Client VIO model is one where the client partition maps part of its local memory into an RTCE table (as defined by the - first window pane of the + first window pane of the “ibm,my-dma-window”property), so that the server partition can get access to that client’s local memory. An example of this is the VSCSI - client (see + client (see for more information). @@ -157,14 +157,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo resources in the process. The following defines the Server VIO model: The server is a server to a client. An example of this is - the VSCSI client (see + the VSCSI client (see ). In this case, the Server VIO model is one where the server gets access to the client partition’s local memory via what the client mapped into an RTCE table. This access is done through the - second window pane of the server’s + second window pane of the server’s “ibm,my-dma-window”property, - which is linked to the first window pane of the client’s + which is linked to the first window pane of the client’s “ibm,my-dma-window”property. @@ -192,7 +192,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo should not be accessed or for protection against improper access modes, like writing to a read only page). More information on TCEs and TCE tables, which are used for physical - IOAs, can be found in + IOAs, can be found in . The RTCE table for Remote DMA (RDMA) is analogous to the TCE table for physical IOAs. The RTCE table does, however, have a little more information in it @@ -201,8 +201,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo TCEs that were created from the RTCE table TCEs. A TCE in an RTCE table is never accessed directly by the partitions software; only though hypervisor hcall()s. For more information - on RTCE table and operations, see - , and + on RTCE table and operations, see + , and . @@ -212,7 +212,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo (“ibm,my-dma-window” property) - The RTCE tables for VIO DMA are pointed to by the + The RTCE tables for VIO DMA are pointed to by the “ibm,my-dma-window” property in the device tree for each virtual device. This property can have one, two, or three triples, each consisting of a Logical I/O @@ -222,11 +222,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo offsets start at 0. The size is the size of the available address space for mapping memory into the RTCE table. This architecture talks about these unique RTCE tables as being - window panes within the + window panes within the “ibm,my-dma-window” property. Thus, there can be up to three window panes for each virtual IOA, depending on the type of IOA. For more on usage of the - window panes, see + window panes, see . @@ -249,7 +249,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo This term refers to when the hypervisor is used (possibly with hardware assist) to move data between server partition and client partition memories or between server partition and - partner partition memories. See + partner partition memories. See . @@ -265,7 +265,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo window pane of the server partition) is used by the hypervisor during the processing of the hcall() to setup the TCE(s) for the physical IOA, and then the physical IOA DMAs directly to or - from the client or partner partition’s memory. See + from the client or partner partition’s memory. See for more information. @@ -276,7 +276,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Stands for Logical Remote DMA and refers to the set of - facilities for synchronous RDMA operations. See also + facilities for synchronous RDMA operations. See also for more information. LRDMA is a separate option. @@ -297,7 +297,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Subordinate CRQ (Sub-CRQ) - Similar to the CRQ, except with notable differences (See + Similar to the CRQ, except with notable differences (See ). @@ -313,7 +313,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo place transport change of status messages into the queue to notify a partition when the connection has been lost (for example, due to the other partition crashing or deregistering - its queue). See + its queue). See for more information. @@ -327,7 +327,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo operations to communicate between partner partitions when the CRQ facility by itself is not sufficient. The Subordinate CRQ Transport never exists without a corresponding Reliable - Command/Response Transport. See + Command/Response Transport. See for more information. @@ -335,25 +335,25 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
-
- + +
VIO Architectural Infrastructure VIO is used in conjunction with the Logical Partitioning option as - described in + described in . For each of a platform’s partitions, the number and type of VIO adapters with the associated interpartition communications paths (if any are defined). These definitions take the architectural form of VIO adapters and are communicated to the partitions as device nodes in their OF device tree. Depending upon the - specific virtual device, their device tree node may be found as a child of + specific virtual device, their device tree node may be found as a child of / (the root node) or in the VIO sub-tree (see below). The VIO infrastructure provides several primitives that may be used to build connections between partitions for various purposes (that is, for various virtual IOA types). These primitives include: - + A Command/Response Queue (CRQ) facility which provides a pipe between partitions. A partition can enqueue an entry on its partner’s @@ -361,21 +361,21 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo receive an interrupt when the queue goes from empty to non-empty, and hence this facility provides a method for an inter-partition interrupt. - + A Subordinate CRQ (Sub-CRQ) facility that may be used in conjunction with the CRQ facility, when the CRQ facility by itself is not sufficient. That is, when more than one queue with more than one interrupt is required by the virtual IOA. - + An extended TCE table called the RTCE table which allows a partition to provide “windows” into the memory of its partition to its partner partition, while maintaining addressing and access control to its memory. - + Remote DMA services that allow a server partition to transfer data to a partner partition’s memory via the RTCE table window panes. This @@ -383,7 +383,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo to and from a partner, which is key in sharing of an IOA in the server partition with its partner partition. - + In addition to the virtual IOAs themselves, this architecture defines a virtual host bridge, and a virtual interrupt source controller. The @@ -391,12 +391,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo controller provides the consistent syntax for communicating the interrupt numbers the partition’s OS sees when the virtual IOAs signal an interrupt. - The general VIO infrastructure is defined in + The general VIO infrastructure is defined in . There are additional infrastructures requirements for the partition managed class based on the - Synchronous VIO model. See + Synchronous VIO model. See . - +
VIO Infrastructure - General This section describes the general OF device tree structure for @@ -404,7 +404,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo describing the interrupt control aspects of virtual IOAs.
- Properties of the + <title>Properties of the <emphasis role="bold"><literal>/vdevice</literal></emphasis> OF Tree Node Most VIO adapters are represented in the OF device tree as children of the @@ -415,7 +415,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - R1-R1--1. @@ -461,9 +461,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Y - Standard property name per - , - specifying the virtual device name, the value shall be + Standard property name per + , + specifying the virtual device name, the value shall be “vdevice” @@ -477,9 +477,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Y - Standard property name per - , - specifying the virtual device type, the value shall be + Standard property name per + , + specifying the virtual device type, the value shall be “vdevice” @@ -506,10 +506,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Y - Standard property name per + Standard property name per , specifying - the virtual device programming models, the value shall include + the virtual device programming models, the value shall include “IBM,vdevice” @@ -563,8 +563,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Y - Standard property name per - , + Standard property name per + , the value shall be 0. No child of this node takes space in the address map as seen by the owning partition. @@ -580,8 +580,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Y - Standard property name per - , + Standard property name per + , the value shall be 1. @@ -595,8 +595,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Y - Standard property name per - , + Standard property name per + , the value shall be 2. The first cell contains the interrupt# as will appear in the XIRR and is used as input to interrupt RTAS calls. The second cell contains the value 0 @@ -667,7 +667,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo Y - The + The /vdevice node appears to contain an interrupt controller. @@ -712,7 +712,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo For DR - Value of + Value of “SLOT”. Any virtual IOA can fit into any virtual slot. @@ -727,7 +727,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo For DR - The virtual location code (see + The virtual location code (see ) @@ -741,11 +741,11 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo For DR - When present replaces the “ibm,drc-indexes”, - “ibm,drc-power-domains”, - “ibm,drc-types” and - “ibm,drc-names” properties. - This single property is a consolidation of the four pre-existing properties + When present replaces the “ibm,drc-indexes”, + “ibm,drc-power-domains”, + “ibm,drc-types” and + “ibm,drc-names” properties. + This single property is a consolidation of the four pre-existing properties and contains all of the required information. @@ -761,7 +761,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo The maximum transfer size for H_SEND_LOGICAL_LAN and H_COPY_RDMA hcall()s. Applies to all VIO which are children of - the + the /vdevice node. Minimum value is 128 KB. @@ -770,9 +770,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
- +
- RTCE Table and Properties of the Children of the + <title>RTCE Table and Properties of the Children of the <emphasis role="bold"><literal>/vdevice</literal></emphasis> Node This architecture defines an extended type of TCE table called a Remote DMA TCE (RTCE) table. An RTCE table is one that is not directly @@ -790,9 +790,9 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo One could also think of each LIOBN pointing to a separate RTCE table, rather than window panes within an RTCE table. . - Children of the + Children of the /vdevice node that support operations which use RTCE - tables (for example, RDMA) contain the + tables (for example, RDMA) contain the “ibm,my-dma-window” property. This property contains one or more (logical-I/O-bus-number, phys, size) triple(s). Each triple represents one window pane in an RTCE table which @@ -811,17 +811,17 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo that memory mapped by that RTCE table’s TCEs. A server partition appends its version of the LIOBN for the partner partition’s RTCE table that represents the partner partition’s RTCE table which it - received through the second entry in the + received through the second entry in the “ibm,my-dma-window” property associated with server partition’s virtual IOA’s device tree node (for - example, see + example, see ). The mapping between the - LIOBN in the second pane of a server virtual IOA’s + LIOBN in the second pane of a server virtual IOA’s “ibm,my-dma-window” property and the corresponding partner partition IOA’s RTCE table is made when the CRQ successfully completes registration. The window panes and the hcall()s that are applicable to those - panes, are defined and used as indicated in + panes, are defined and used as indicated in . @@ -862,7 +862,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - + I/O address range which is available to map local partition memory for use by the hypervisor @@ -870,12 +870,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - + I/O address range which is available to map local partition memory to make it available to the hypervisor use (access to the CRQ and any Sub-CRQs). - + For clients which support RDMA operations from their partner partition to their local memory (for example, VSCSI), this I/O address range is available to map local partition @@ -887,13 +887,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - + I/O address range which is available to map local partition memory for use by the hypervisor (for access by H_COPY_RDMA requests, and for access to the CRQ, any Sub-CRQs). - + This window is not available to any other partition. @@ -918,12 +918,12 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo - + I/O address range which corresponds to a window pane of the partner partition: linked to the first window pane for Client/Server model connections. - + Used to get access to the partner partition’s memory from the hypervisor that services the local partition for use as source or destination in Copy RDMA requests or for @@ -941,37 +941,37 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo
- The + The “ibm,my-dma-window” property is the per - device equivalent of the + device equivalent of the “ibm,dma-window” property found in nodes representing bus bridges. - Children of the + Children of the /vdevice node contain virtual location codes in their - + “ibm,loc-code” properties. The invariant assignment number is uniquely generated when the virtual IOA is assigned to the partition and remains invariably associated with that virtual IOA - for the duration of the partition definition. For more information, see + for the duration of the partition definition. For more information, see .
- +
VIO Interrupt Control There are two hcall()s that work in conjunction with the RTAS calls - - ibm,int-on, - ibm,int-off, - ibm,set-xive and + + ibm,int-on, + ibm,int-off, + ibm,set-xive and ibm,get-xive, which manage the state of the interrupt presentation controller logic. These hcall()s provide the equivalent of IOA control registers used to control IOA interrupts. The - usage of these two hcall()s is summarized in + usage of these two hcall()s is summarized in . The detail of the H_VIO_SIGNAL is shown after this table and the detail of the applicable - H_VIOCTL subfunctions can be found in - , - , and + H_VIOCTL subfunctions can be found in + , + , and . @@ -1024,7 +1024,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo H_VIOCTL - OF device tree + OF device tree “interrupts” property @@ -1051,13 +1051,13 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdo This H_VIO_SIGNAL hcall() manages the interrupt mode of a virtual adapter’s CRQ interrupt signalling logic. There are two modes: Disabled, and Enabled. - The first interrupt of the + The first interrupt of the “interrupts” property is for the CRQ. - + Syntax: - + - + Parameters: - + - unit-address: unit address per device tree node + unit-address: unit address per device tree node “reg” property. - + mode: - + Bit 63 controls the first interrupt specifier given in the - virtual IOA’s + virtual IOA’s “interrupts” property, and bit 62 the second. High order bits not associated with an interrupt source as defined in the previous sentence should be set to zero by the caller and ignored by the hypervisor. - + A bit value of 1 enables the specified interrupt, a bit value of 0 disables the specified interrupt. - + - + - + Semantics: - + Validate that the unit address belongs to the partition and to a vdevice IOA, else H_Parameter. - + Validate that the mode is one of those defined, else H_Parameter. - + Establish the specified mode. - + Return H_Success. - + @@ -1134,7 +1134,7 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ - R1-R1--1. @@ -1142,123 +1142,123 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ LPAR mode. - + - R1-R1--2. For all VIO options: The platform’s OF device - tree must include, as a child of the - root node, a node of type + tree must include, as a child of the + root node, a node of type vdevice as the parent of a sub-tree representing the - virtual IOAs assigned to the partition (see + virtual IOAs assigned to the partition (see for details). - + - R1-R1--3. - For all VIO options: The platform’s - /vdevice node must contain properties as defined in + For all VIO options: The platform’s + /vdevice node must contain properties as defined in . - + - R1-R1--4. For all VIO options: If the platform is going to limit the size of virtual I/O data copy operations (e.g., - H_SEND_LOGICAL_LAN and H_COPY_RDMA), then the platform’s - /vdevice node must contain the + H_SEND_LOGICAL_LAN and H_COPY_RDMA), then the platform’s + /vdevice node must contain the “ibm,max-virtual-dma-size” property, and the value of this property must be at least 128 KB. - + - R1-R1--5. For all VIO options: The interrupt server numbers for all interrupt source numbers, virtual and physical, must come from the - same name space and are defined by the + same name space and are defined by the “ibm,interrupt-buid-size” property in the PowerPC External Interrupt Presentation Controller Node. - + - R1-R1--6. For all VIO options: The virtual interrupts for all - children of the + children of the /vdevice node must, upon transfer of control to the - booted partition program, be masked as would be the result of an + booted partition program, be masked as would be the result of an ibm,int-off RTAS call specifying the virtual interrupt source number. - + - R1-R1--7. For all VIO options with the Reliable Command/Response option: The platform must specify the CRQ interrupt as the - first interrupt in the + first interrupt in the “interrupts” property for a virtual IOA. - + - R1-R1--8. - For the SMC options: + For the SMC options: The platform must specify the ASQ interrupt as the second interrupt in the “interrupts” property for a virtual IOA. - + - R1-R1--9. For all VIO options: The platform must implement the - H_VIO_SIGNAL hcall() as defined in + H_VIO_SIGNAL hcall() as defined in . - + - R1-R1--10. For all VIO options: The platform must assign an - invariant virtual location code to each virtual IOA as described in + invariant virtual location code to each virtual IOA as described in . - R1-R1--11. @@ -1266,14 +1266,14 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ - + - R1-R1--12. - For all VIO options: The - phys of each + For all VIO options: The + phys of each “ibm,my-dma-window” property triple (window pane) must have a value of zero and the LIOBN must be unique. @@ -1288,42 +1288,42 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ OS’s. - + - R1-R1--13. For the VSCSI option: For the server - partition, there must exist two triples (two window panes) in the + partition, there must exist two triples (two window panes) in the “ibm,my-dma-window” property and the size - field of the second triple (second window pane) of an + 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 first triple (first window - pane) of the associated partner partition’s + pane) of the associated partner partition’s “ibm,my-dma-window” property. - + - R1-R1--14. For the SMC option: There must exist three triples (three window panes) in the - “ibm,my-dma-window” + “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 + 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. - + - R1-R1--15. @@ -1331,7 +1331,7 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ RTCE tables for virtual IOAs, as pointed to by the partitions’ first window pane of the - + “ibm,my-dma-window” property, and the TCEs that they contain (as built by the TCE hcall()s) must be persistent across partner partition reboots and across partner partition deregister @@ -1342,36 +1342,36 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ the IOA will also remove the RTCE table). - + - R1-R1--16. For all VIO options: The connection between the - second window pane of the + second window pane of the “ibm,my-dma-window” property for a partition and its corresponding window pane in the partner partition (first window pane) must be broken by the platform when either partition deregisters its CRQ or when either partition terminates, and the platform must invalidate any redirected TCEs copied from the said second window - pane (for information on invalidation of TCEs, see + pane (for information on invalidation of TCEs, see ). - + - R1-R1--17. For all VIO options: The following window panes of - the “ibm,my-dma-window” + the “ibm,my-dma-window” property, when they exist, must support the following specified hcall()s, when they are implemented: - + For the first window pane: H_PUT_TCE, H_GET_TCE, H_PUT_TCE_INDIRECT, H_STUFF_TCE @@ -1381,12 +1381,12 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ For the second window pane: H_PUT_RTCE, H_REMOVE_RTCE, H_PUT_RTCE_INDIRECT - + - + - R1-R1--18. @@ -1397,44 +1397,44 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ configurations. - + - R1-R1--19. - For all VIO options: Any child node of the + For all VIO options: Any child node of the /vdevice node that is not defined by this - architecture must contain the + architecture must contain the “used-by-rtas” property. Implementation Notes: - + - Relative to Requirement + Relative to Requirement , partner partitions being the same partition makes sense from a product development standpoint. - The + The ibm,partner-control RTAS call does not make sense if the partner partitions are the same partition. - + - + - R1-R1--20. For all VIO options: The platform must implement the - H_VIOCTL hcall() following the syntax of - and semantics specified by + H_VIOCTL hcall() following the syntax of + and semantics specified by . @@ -1442,7 +1442,7 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ - +
Shared Logical Resources The sharing of resources, within the boundaries of a single @@ -1450,10 +1450,10 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ clients (those owning the associated client virtual IOAs) is controlled by the hcall()s described in this section. The owning partition retains control of and access to the resources and can ask for their return or - indeed force it. Refer to + indeed force it. Refer to for a graphic representation of the state transitions involved in sharing logical resources. - +
Shared Logical Resource State Transitions @@ -1516,7 +1516,7 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ resources. This architecture does not specify a method of implementation, however, for the sake of clarifying the specified function, the following - example implementation is given, refer to + example implementation is given, refer to . Assume that the hypervisor maintains for each partition a logical to physical translation table (2) (used to verify the partition’s virtual to logical mapping @@ -1553,7 +1553,7 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ to the owner’s logical resource control structure (3).  
- Example Implementation of Control Structures + <title>Example Implementation of Control Structures for Shared Logical Resources @@ -1585,7 +1585,7 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ - R1-R1--1. @@ -1598,9 +1598,9 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ . - + - R1-R1--2. @@ -1633,7 +1633,7 @@ hcall ( const int64 H_VIO_SIGNAL, /* Function Code */ The “logical” parameter identifies the starting “address” of the subset of the logical resource to be shared. The form of this “address” is resource dependent, and is - given in + given in . @@ -1665,7 +1665,7 @@ hcall ( const uint64 H_GRANT_LOGICAL, /* Returns in R4 a cookie representing a * );]]> - + Parameters:   @@ -1842,7 +1842,7 @@ hcall ( const uint64 H_GRANT_LOGICAL, /* Returns in R4 a cookie representing a * 0x4 - 24 bit Interrupt # (as would be used in + 24 bit Interrupt # (as would be used in ibm,get-xive) in low order 3 bytes in logical-lo; logical-hi not used (should be = 0) @@ -1903,32 +1903,32 @@ hcall ( const uint64 H_GRANT_LOGICAL, /* Returns in R4 a cookie representing a * the shared logical resource, and thus the partner partition that is to share the logical resource. - + Semantics: - + Verify that the flags parameter specifies a supported logical resource type, else return H_Parameter. - + Verify that the logical address validly identifies a logical resource of the type specified by the flags parameter and owned/shared by the calling partition, else return H_Parameter; unless: - + The logical address’s page number represents a page that has been rescinded by the owner, then return H_RESCINDED. - + There exists a grant restriction on the logical resource, then return H_Permission. - + @@ -1937,19 +1937,19 @@ hcall ( const uint64 H_GRANT_LOGICAL, /* Returns in R4 a cookie representing a * subset (up to the full size) of the logical resource specified by the logical address parameter, else return H_Parameter. - + Verify that the unit-address is for a virtual IOA owned by the calling partition, else return H_Parameter. - + If the partner partition’s client virtual IOA has sufficient resources, generate hypervisor structures to represent, for hypervisor management purposes, including any grant restrictions, the specified shared logical resource, else return H_NOMEM. - + Generate a cookie associated with the hypervisor structures created in the previous step that the partner partition associated with @@ -1958,12 +1958,12 @@ hcall ( const uint64 H_GRANT_LOGICAL, /* Returns in R4 a cookie representing a * can use to reference said structures via the H_RESCIND_LOGICAL hcall(). - + Place the cookie generated in the previous step in R4 and return H_Success. - +
@@ -2003,7 +2003,7 @@ hcall ( const uint64 H_RESCIND_LOGICAL, /* Invalidates a cookie representing a * );]]> - + Parameters: flags: The flags subfunction code field (bits 16-23) two values are @@ -2011,22 +2011,22 @@ hcall ( const uint64 H_RESCIND_LOGICAL, /* Invalidates a cookie representing a * cookie: The handle returned by H_GRANT_LOGICAL representing the logical resource to be rescinded. - + Semantics: - + Verify that the cookie parameter references an outstanding instance of a shared logical resource owned/accepted by the calling partition, else return H_Parameter. - + Verify that the flags parameter is one of the supported values, else return H_Paramter. - + If the “force” flag is specified Implementations should provide mechanisms to ensure that reserved @@ -2039,23 +2039,23 @@ hcall ( const uint64 H_RESCIND_LOGICAL, /* Invalidates a cookie representing a * any cookies generated by the client partition that refer to the logical resource referenced by the original cookie being rescinded. - + If the client partition has the resource referenced by cookie is in the available for mapping via its logical to physical mapping table (the resource was accepted and not returned), return H_Resource. - + Verify that resource reference by cookie is not mapped by the client partition, else return H_PARTIAL. - + Hypervisor reclaims control structures referenced by cookie and returns H_Success. - + @@ -2084,40 +2084,40 @@ hcall ( const uint64 H_ACCEPT_LOGICAL, /* Returns in R4 handle of a shared logic );]]> - + Parameters: cookie: The handle returned by H_GRANT_LOGICAL representing the logical resource to be accepted. - + Semantics: - + Verify that the cookie parameter is valid for the calling partition, else return H_Parameter. - + If the cookie represents a logical resources that has been rescinded by the owner, return H_RESCINDED. - + - + Map the resources represented by the cookie parameter, with any attendant access restrictions, into the lowest available logical address of the calling partition consistent with constraints of size and alignment and place the selected logical address into R4. - + Return H_Success. - + @@ -2161,27 +2161,27 @@ hcall ( const uint64 H_RETURN_LOGICAL, /* Removes the logical resource from the cookie: The handle returned by H_GRANT_LOGICAL representing the logical resource to be returned. - + Semantics: - + Verify that the cookie parameter references an outstanding instance of a shared logical resource accepted by the calling partition, else return H_Parameter. - + Remove the referenced logical resource from the calling partition’s logical address map. - + Verify that no virtual to logical mappings exist for the referenced resource, else return H_Resource. - + This operation may require extensive processing -- in some cases the hcall may return H_Busy to allow for improved system responsiveness @@ -2189,18 +2189,18 @@ hcall ( const uint64 H_RETURN_LOGICAL, /* Removes the logical resource from the hypervisor’s state structures such that after some number of repeated calls the function is expected to finish. - + - + Return H_Success. - + - +
H_VIOCTL The H_VIOCTL hypervisor call allows the partition to manipulate or @@ -2208,7 +2208,7 @@ hcall ( const uint64 H_RETURN_LOGICAL, /* Removes the logical resource from the
Command Overview - + Syntax: @@ -2229,58 +2229,58 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ );]]> - + Parameters: - + unit-address: As specified. - + - subfunction: Specific subfunction to perform; see + subfunction: Specific subfunction to perform; see . - + parm-1: Specified in subfunction semantics. - + parm-2: Specified in subfunction semantics. - + parm-3: Specified in subfunction semantics. - + - + Semantics: - + Validate that the subfunction is implemented, else return H_Not_Found. - + Validate the unit-address, else return H_Parameter. - + Validate the subfunction is valid for the given virtual IOA, else return H_Parameter. - + - Refer to + Refer to to determine the semantics for the given subfunction. - +  
@@ -2583,7 +2583,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ Get_ILLAN_SWITCHING_MODE - For any ILLAN adapter with the + For any ILLAN adapter with the “ibm,trunk-adapter” property @@ -2600,7 +2600,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ DISABLE_INACTIVE_TRUNK_RECEPTION - For any ILLAN adapter with the + For any ILLAN adapter with the "ibm,trunk-adapter" property @@ -2626,6 +2626,70 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ + + + 0x18 + + + VNIC_SERVER_STATUS + + + For VNIC servers + + + + + + + + + + 0x19 + + + GET_SESSION_TOKEN + + + For VNIC clients + + + + + + + + + + 0x1A + + + SESSION_ERROR_DETECTED + + + For VNIC clients + + + + + + + + + + 0x1B + + + GET_VNIC_SERVER_INFO + + + For VNIC servers + + + + + + +
@@ -2635,135 +2699,135 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
GET_VIOA_DUMP_SIZE Subfunction Semantics - + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter. - + The hypervisor calculates the size necessary for passing opaque firmware data describing current virtual IOA state to the partition for purposes of error logging and RAS, and returns H_Success, with the required size in R4. - +
- +
GET_VIOA_DUMP Subfunction Semantics - + - If the given virtual IOA has an + If the given virtual IOA has an “ibm,my-dma-window” property in its device tree, then parm-1 is an eight byte output descriptor. The high order byte of an output descriptor is control, the next three bytes are a length field of the buffer in bytes, and the low order four bytes are a TCE mapped I/O address of the start of a buffer in I/O address space. The high order control byte must be set to zero. The TCE mapped I/O address - is mapped via the first window pane of the + is mapped via the first window pane of the “ibm,my-dma-window” property. - + - If the given virtual IOA has no + If the given virtual IOA has no “ibm,my-dma-window” property in its device tree, then parm-1 shall be a logical real, page-aligned address of a 4 K page used to return the virtual IOA dump. - + Validate parm-2 and parm-3 are set to zero, else return H_Parameter. - + If parm-1 is an output descriptor, then - + Validate the I/O address range is in the required DMA window and is mapped by valid TCEs, else return H_Parameter. - + Transfer as much opaque hypervisor data as fits into the output buffer as specified by the output descriptor. - + If all opaque data will not fit due to size, return H_Constrained, else return H_Success. - + - + If parm-1 is a logical real address, then - + Validate the logical real address is valid for the partition, else return H_Parameter. - + Transfer as much opaque hypervisor data as will fit into the passed logical real page, with a maximum of 4 K. - + If all opaque data will not fit in the page due to size, return H_Constrained, else return H_Success. - + - +
- +
GET_ILLAN_NUMBER_VLAN_IDS Subfunction Semantics - + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter. - + The hypervisor returns H_Success, with the number of VLAN IDs (PVID + VIDs) in R4. This subfunction allows the partition to allocate the correct amount of space for the call: H_VIOCTL(GET_VLAN_ID_LIST). - +
- +
GET_ILLAN_VLAN_ID_LIST Subfunction Semantics - + parm-1 is an eight byte output descriptor. The high order byte of an output descriptor is control, the next three bytes are a length field of the buffer in bytes, and the low order four bytes are a TCE mapped I/O address of the start of a buffer in I/O address space. The high order control byte must be set to zero. The TCE mapped I/O address is mapped - via the first window pane of the + via the first window pane of the “ibm,my-dma-window” property. - + Validate parm-2 and parm-3 are set to zero, else return H_Parameter. - + Validate the I/O address range is in the required DMA window and is mapped by valid TCEs, else return H_Parameter. - + Transfer the VLAN_ID_LIST into the output buffer as specified by the output descriptor. The data will be an array of two byte values, @@ -2772,42 +2836,42 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ documentation. Any unused space in the output buffer will be zeroed. - + If all VLAN IDs do not fit due to size, return H_Constrained. - + Return H_Success - +
- +
GET_ILLAN_SWITCH_ID Subfunction Semantics - + parm-1 is an eight byte output descriptor. The high order byte of an output descriptor is control, the next three bytes are a length field of the buffer in bytes, and the low order four bytes are a TCE mapped I/O address of the start of a buffer in I/O address space. The high order control byte must be set to zero. The TCE mapped I/O address is mapped - via the first window pane of the + via the first window pane of the “ibm,my-dma-window” property. - + Validate parm-2 and parm-3 are set to zero, else return H_Parameter. - + Validate the I/O address range is in the required DMA window and is mapped by valid TCEs, else return H_Parameter. - + Transfer the GET_ILLAN_SWITCH_ID into the output buffer as specified by the output descriptor. The data will be a string of ASCII @@ -2815,134 +2879,134 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ adapter is connected. Any unused space in the output buffer will be zeroed. - + If the switch identifier does not fit due to size, return H_Constrained. - + Return H_Success - +
DISABLE_MIGRATION Subfunction Semantics - When this subfunction is implemented, the + When this subfunction is implemented, the “ibm,migration-control” property exists - in the + in the /vdevice OF device tree node. - + Validate that parm-1, parm-2, and parm-3 are all set to zero, else return H_Parameter. - + If no partner is connected, then return H_Closed. - + Prevent the migration of the partner partition to the destination server until either the ENABLE_MIGRATION subfunction is called or H_FREE_CRQ is called. - + Return H_Success. - +
ENABLE_MIGRATION Subfunction Semantics - When this subfunction is implemented, the + When this subfunction is implemented, the “ibm,migration-control” property exists - in the + in the /vdevice OF device tree node. - + Validate that parm-1, parm-2, and parm-3 are all set to zero, else return H_Parameter. - + Validate that the migration of the partner partition to the destination server was previously prevented with DISABLE_MIGRATION subfunction, else return H_Parameter. - + Enable the migration of the partner partition. - + Return H_Success. - +
GET_PARTNER_INFO Subfunction Semantics - + Parm-1 is an eight byte output descriptor. The high order byte of an output descriptor is control, the next three bytes are a length field of the buffer in bytes, and the low order four bytes are a TCE mapped I/O address of the start of a buffer in I/O address space. The high order control byte must be set to zero. The TCE mapped I/O address is mapped - via the first window pane of the + via the first window pane of the “ibm,my-dma-window” property. - + Validate parm-2 and parm-3 are set to zero, else return H_Parameter. - + Validate the I/O address range is in the required DMA window and is mapped by valid TCEs, else return H_Parameter. - + If the output buffer is not large enough to fit all the data, then return H_Constrained. - + If no partner is connected and more than one possible partner exists, then return H_Closed. - + Transfer the eight byte partner partition ID into the first eight bytes of the output buffer. - + Transfer the eight byte unit address into the second eight bytes of the output buffer. - + Transfer the NULL-terminated Converged Location Code associated with the partner unit address and partner partition ID immediately following the unit address. - + Zero any remaining output buffer. - + Return H_Success. - +
@@ -2951,58 +3015,58 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ hypervisor. In this way, there is assurance that the WWPNs are accurate. - + Parm-1 is an eight byte output descriptor. The high order byte of an output descriptor is control, the next three bytes are a length field of the buffer in bytes, and the low order four bytes are a TCE mapped I/O address of the start of a buffer in I/O address space. The high order control byte must be set to zero. The TCE mapped I/O address is mapped - via the first window pane of the + via the first window pane of the “ibm,my-dma-window” property. - + Validate parm-2 and parm-3 are set to zero, else return H_Parameter. - + Validate the I/O address range is in the required DMA window and is mapped by valid TCEs, else return H_Parameter. - + If the output buffer is not large enough to fit all the data, return H_Constrained. - + If no partner is connected, return H_Closed. - + - Transfer the first eight byte WWPN, which is represented in the - vfc-client node of the partner partition in the + Transfer the first eight byte WWPN, which is represented in the + vfc-client node of the partner partition in the “ibm,port-wwn-1” parameter, into the first eight bytes of the output buffer. - + - Transfer the second eight byte WWPN, which is represented in the - vfc-client node of the partner partition in the + Transfer the second eight byte WWPN, which is represented in the + vfc-client node of the partner partition in the “ibm,port-wwn-2” parameter, into the second eight bytes of the output buffer. - + Zero any remaining output buffer. - + Return H_Success. - +
@@ -3020,21 +3084,21 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ receive an H_Not_Found return code indicating the platform does not implement this subfunction. - + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter. - + Disable all CRQ and any Sub-CRQ interrupts associated with unit-address. - + Return H_Success. - +
@@ -3051,29 +3115,29 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ receive an H_Not_Found return code indicating the platform does not implement this subfunction. - + Parm-1 is the interrupt number of the interrupt to be disabled. - For an interrupt associated with a CRQ this number is obtained from the + For an interrupt associated with a CRQ this number is obtained from the “interrupts” property in the device tree For an interrupt associated with a Sub-CRQ this number is obtained during the registration of the Sub-CRQ (H_REG_SUB_CRQ). - + Validate parm-1 is a valid interrupt number for a CRQ or Sub-CRQ for the virtual IOA defined by parm-1 and that parm-2 and parm-3 are set to zero, else return H_Parameter. - + Disable interrupt specified by parm-1. - + Return H_Success. - +
@@ -3090,46 +3154,46 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ receive an H_Not_Found return code indicating the platform does not implement this subfunction. - + Parm-1 is the interrupt number of the interrupt to be enabled. - For an interrupt associated with a CRQ this number is obtained from the + For an interrupt associated with a CRQ this number is obtained from the “interrupts” property in the device tree For an interrupt associated with a Sub-CRQ this number is obtained during the registration of the Sub-CRQ (H_REG_SUB_CRQ). - + Validate parm-1 is a valid interrupt number for a CRQ or Sub-CRQ for the virtual IOA defined by unit-address and that parm-2 and parm-3 are set to zero, else return H_Parameter. - + Enable interrupt specified by parm-1. - + Return H_Success. - +
GET_ILLAN_MAX_VLAN_PRIORITY Subfunction Semantics - + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter. - + The hypervisor returns H_Success, with the maximum IEEE 802.1Q VLAN priority returned in R4. If no priority limits are in place, the maximum VLAN priority is returned in R4. - +
@@ -3137,44 +3201,44 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ This subfunction allows the partition to allocate the correct amount of space for the GET_MAC_ACLS Subfunction call. - + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter. - + The hypervisor returns H_Success, with the number of allowed MAC addresses returned in R4. If no MAC access control limits are in place, 0 is returned in R4. - +
GET_MAC_ACLS Subfunction Semantics - + parm-1 is an eight byte output descriptor. The high order byte of an output descriptor is control, the next three bytes are a length field of the buffer in bytes, and the low order four bytes are a TCE mapped I/O address of the start of a buffer in I/O address space. The high order control byte must be set to zero. The TCE mapped I/O address is mapped - via the first window pane of the + via the first window pane of the “ibm,my-dma-window” property. - + Validate parm-2 and parm-3 are set to zero, else return H_Parameter. - + Validate the I/O address range is in the required DMA window and is mapped by valid TCEs, else return H_Parameter. - + Transfer the allowed MAC addresses into the output buffer as specified by the output descriptor. The data will be an array of 8 byte @@ -3182,43 +3246,43 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ containing the 6 byte MAC address. Any unused space in the output buffer are zeroed. - + If all allowed MAC addresses do not fit due to size, return H_Constrained. - + Return H_Success - +
GET_PARTNER_UUID Subfunction Semantics - + Validate parm-1, parm-2 and parm-3 are set to zero, else return H_Parameter. - + If no partner is connected and more than one possible partner exists, then return H_Closed. - + Transfer into registers R4 (High order 8 bytes) and R5 (low order 8 bytes) of the UUID of the client partition that owns the virtual device ( for the format of the UUID string. - + Return H_Success - +
@@ -3232,48 +3296,48 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ Semantics: - + Validate that parm-1, parm-2, and parm-3 are all set to zero, else return H_Parameter. - + If the firmware associated with the virtual adapter can not be reset, return H_Constrained. - + Reset the firmware associated with the virtual adapter. - + Return H_Success. - +
GET_ILLAN_SWITCHING_MODE Subfunction Semantics - + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter. - + Validate that the given virtual IOA is a ILLAN adapter with the “ibm,trunk-adapter”, else return H_Parameter. - + The hypervisor returns H_Success, with the current switching mode in R4. If the switching mode is VEB mode, R4 will have a 0. If the switching mode is VEPA mode, R4 will have a 1. - +
@@ -3287,115 +3351,401 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ ENABLED. The value is reset on a successful H_FREE_LOGICAL_LAN hcall or reboot/power change of the partition owning the ILLAN adapter. - + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter. - + Validate that the given virtual IOA is a ILLAN adapter with the “ibm,trunk-adapter”, else return H_Parameter. - + The hypervisor disables reception of packets for this adapter when it is not the Active Trunk Adapter. - + Return H_Success. - +
GET_MAX_REDIRECTED_MAPPINGS Subfunction Semantics - - This sub-function retrieves the maximum number of additional + + This sub-function retrieves the maximum number of additional redirected mappings for the specified adapter. - + - Validate parm-1, parm-2, and parm-3 are set to zero, else return + Validate parm-1, parm-2, and parm-3 are set to zero, else return H_Parameter - + - Validate that the given virtual IOA is an RDMA-capable server adapter, + Validate that the given virtual IOA is an RDMA-capable server adapter, else return H_Parameter. - + - Store the maximum number of additional redirected mappings for + Store the maximum number of additional redirected mappings for the LIOBN in R4. - + Store the maximum number of redirections per client IOBA in R5. - + Return H_Success
-
+
+ VNIC_SERVER_STATUS Subfunction Semantics + + This subfunction is used to report the status of the physical + backing device corresponding to a specific VNIC server adapter. + Additionally, this subfunction is used as a heartbeat mechanism + that the hypervisor utilizes to ensure the backing device associated + with the virtual adapter is responsive. + + + + parm-1 is an enumerated value reflecting the physical backing + evice status. Validate that parm-1 is one of the following values: + 0x1 (Operational), 0x2 (LinkDown), or 0x3 (AdapterError). Otherwise, + return H_Parameter. + + + + parm-2 is a value, in milliseconds, that the caller utilizes + to specify how long the hypervisor should wait for the next server + status vioctl call. + + + + Validate that parm-3 is zero, else return H_Parameter. + + + + If the CRQ for the server adapter has not yet been registered, + return H_State. + + + + Return H_Success. + + +
+ +
+ GET_SESSION_TOKEN Subfunction Semantics + + This subfunction is used to obtain a session token from a VNIC client adapter. + This token is opaque to the caller and is intended to be used in tandem with the + SESSION_ERROR_DETECTED vioctl subfunction. + + On platforms that implement the partition migration option, after partition + migration the support for this subfunction might change, and the caller + should be prepared to receive an H_Not_Found return code indicating the platform + does not implement this subfunction. + + + + Validate that parm-1, parm-2, and parm-3 are 0, else return + H_Parameter. + + + + Return H_Success, with the session token in R4. + + +
+ +
+ SESSION_ERROR_DETECTED Subfunction Semantics + + This subfunction is used to report that the currently active + backing device for a VNIC client adapter is behaving poorly, and + that the hypervisor should attempt to fail over to a different backing + device, if one is available. + + On platforms that implement the partition migration option, + after partition migration the support for this subfunction might change, + nd the caller should be prepared to receive an H_Not_Found return code + indicating the platform does not implement this subfunction. + + + + parm-1 is a VNIC session token. This token should be obtained + from the GET_SESSION_TOKEN vioctl subfunction. + + + + Validate that parm-2 and parm-3 are 0, else return H_Parameter. + + + + Validate that the session token parameter corresponds to the current + VNIC session, else return H_State. + + + + Validate that the active server status is Operational, else return + H_Constrained. + + + + If the server status is Operational, change the server status to + NetworkError and attempt to fail over to a different backing device. + If there are no suitable servers to fail over to, return H_Constrained. + + + + If the client successfully failed over to another backing device + as a result of this subfunction call, return H_Success. + + +
+ +
+ GET_VNIC_SERVER_INFO Subfunction Semantics + + This subfunction is used to fetch information about a VNIC server + adapter. + + + + parm-1 is an eight byte output descriptor. The high order + byte of an output descriptor is control, the next three bytes are + a length field of the buffer in bytes, and the low order four bytes + are a TCE mapped I/O address of the start of a buffer in I/O address + space. The high order control byte must be set to zero. The TCE mapped + I/O address is mapped via the first window pane of the + “ibm,my-dma-window” + property. + + + + Validate that parm-2 and parm-3 are 0, else return H_Parameter. + + + + Populate the TCE mapped buffer with the following information. + Note that if the buffer descriptor (parm-1) describes an output buffer + that is not large enough to hold the following information, the server + information will be truncated to the size of the output buffer and the + buffer will be populated with the truncated information. + + + + + + + + + + + Field + + + Byte Offset + + + Size + + + Description + + + + + + + Version + + + 0 + + + 8 + + + The format version of the provided information. + The first supported version is 1. + + + + + Active + + + 8 + + + 8 + + + Boolean value describing whether or not this server + adapter is currently the active server for the client + adapter it is mapped to. + + + 0x0 - The server is not currently active. + + + 0x1 - The server is currently the active backing + device for the client. + + + + + + + + Status + + + 16 + + + 8 + + + Enumeration value corresponding to the current + virtual adapter status. + + + + 0x1 - Operational - The server adapter is working + as expected. + + + 0x2 - LinkDown - The SR-IOV backing device's + physical link is down. + + + 0x3 - AdapterError - SR-IOV adapter is undergoing + EEH. + + + 0x4 - PoweredOff - The virtual server adapter + or its hosting partition is powered off. + + + 0x5 - NetworkError - VNIC client detected a network + issue with this adapter. + + + 0x6 - Unresponsive - The hypervisor is not reliably + receiving VNIC_SERVER_STATUS vioctl calls from the VNIC + server. + + + + + + + + + Priority + + + 24 + + + 1 + + + The current priority of this server adapter. Lower + values take precedence over larger values. + + + + + Reserved + + + 25 + + + 7 + + + This field is reserved and must be zero. + + + + + + + + + + Return H_Success. + + +
+
Partition Managed Class Infrastructure - General - In addition to the general requirements for all VIO described in + In addition to the general requirements for all VIO described in , the architecture for the partition managed class of VIO defines several other infrastructures: - + A Command/Response Queue (CRQ) that allows communications back - and forth between the server partition and its partner partition (see + and forth between the server partition and its partner partition (see ). - + A Subordinate CRQ (Sub-CRQ) facility that may be used in conjunction with the CRQ facility, when the CRQ facility by itself is not sufficient. That is, when more than one queue with more than one - interrupt is required by the virtual IOA. See + interrupt is required by the virtual IOA. See . - + A mechanism for doing RDMA, which includes: - + A mechanism called Copy RDMA that can be used by the device driver to move blocks of data between memory of the server and partner partitions - + A mechanism for Redirected RDMA that allows the device driver to direct DMA of data from the server partition’s physical IOA to or - from the partner partition’s memory (see + from the partner partition’s memory (see ). - + - + The mechanisms for the synchronous type VIO are described as follows: - + - +   @@ -3425,15 +3775,15 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ boundary within partition memory. The queue is organized as a circular buffer of 16 byte long elements. The queue is mapped into contiguous I/O addresses via the TCE mechanism and RTCE table (first window pane). The - I/O address and length of the queue are registered by + I/O address and length of the queue are registered by . This registration process tells the hypervisor where to find the virtual IOA’s CRQ.
- +
CRQ Entry Format Each CRQ entry consists of a 16 byte element. The first byte of a - CRQ entry is the Header byte and is defined in + CRQ entry is the Header byte and is defined in .   @@ -3480,7 +3830,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ Valid Command/Response entry -- the second byte defines - the entry format (for example, see + the entry format (for example, see ). @@ -3498,7 +3848,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ Valid Initialization Command/Response entry -- the second - byte defines the entry format. See + byte defines the entry format. See . @@ -3516,7 +3866,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ Valid Transport Event -- the second byte defines the - specific transport event. See + specific transport event. See . @@ -3530,12 +3880,12 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ second byte of the entry is reserved for a Format byte to enable the definitions of the content and protocol between using pairs to evolve over time. The definition of the second byte of the Valid - Command/Response entry is beyond the scope of this architecture. + Command/Response entry is beyond the scope of this architecture. presents example VSCSI format byte values. The Valid Initialization Command/Response entry (Header byte 0xC0) is used during virtual IOA initialization sequences. The second byte of - this type entry is architected and is as defined in + this type entry is architected and is as defined in . This format is used for initialization operations between communicating partitions. The remaining bytes (byte three and beyond) of the Valid Initialization @@ -3616,7 +3966,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ entry specifies a Valid Transport Event, then the second byte of the CRQ entry defines the type of transport event. The Format byte (second byte) of a Valid Transport Event queue entry is architected and is as defined - in + in ).  
@@ -3712,7 +4062,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ disables the associated CRQ such that any H_SEND_CRQ hcall() ( ) to the associated CRQ returns H_Closed until the CRQ has been explicitly enabled using the H_ENABLE_CRQ - hcall (See + hcall (See ). @@ -3727,7 +4077,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ to maintain independent pointers to the next element they will be respectively using. A sender uses an infrastructure dependent method to enter a 16 byte - message on its partner’s queue (see + message on its partner’s queue (see ). Prior to enqueueing an entry on the CRQ, the platform first checks if the session to the partner’s queue is open, and there is a free entry, if not, it @@ -3735,7 +4085,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ copied into the next free queue element, potentially notifying the receiver, and returns a successful status to the caller. At the receiver’s option, it may be notified via an interrupt - when an element is enqueued to its CRQ. See + when an element is enqueued to its CRQ. See . When the receiver has finished processing a queue entry, it writes the header to the value 0x00 to invalidate the entry and free it for @@ -3752,7 +4102,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ The receiver can set the virtual interrupt associated with its CRQ to one of two modes. These are: - + Disabled (An enqueue interrupt is not signaled.) @@ -3761,7 +4111,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ Enabled (An enqueue interrupt is signaled on every enqueue) - + Note: An enqueue is considered a pulse not a level. The pulse then sets the memory element within the emulated interrupt @@ -3779,7 +4129,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ to be expected. That is, an enqueue can happen in a window around the H_EOI hcall(). Therefore, the receiver should poll the CRQ after an H_EOI to prevent losing initiative. - See ) for + See ) for information about interrupt control. @@ -3811,46 +4161,46 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ - R1-R1--1. For the CRQ facility: The platform must implement the - CRQ as specified in + CRQ as specified in . - + - R1-R1--2. For the CRQ facility: The platform must reject CRQ definitions that are not 4 KB aligned. - + - R1-R1--3. For the CRQ facility: The platform must reject CRQ definitions that are not a multiple of 4 KB long. - + - R1-R1--4. For the CRQ facility: The platform must reject CRQ definitions that are not mapped relative to the TCE mapping defined by - the first window pane of the virtual IOA’s + the first window pane of the virtual IOA’s “ibm,my-dma-window” property. - + - R1-R1--5. For the CRQ facility: @@ -3860,9 +4210,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ 16 byte aligned. - + - R1-R1--6. For the CRQ facility: @@ -3871,22 +4221,22 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ contains 0x00), else the enqueue operation fails. - + - R1-R1--7. For the CRQ facility: The platform must enqueue the 16 bytes specified in the validated enqueue request as specified in - Requirement + Requirement except as required by - Requirement + Requirement . - + - R1-R1--8. For the CRQ facility: @@ -3896,9 +4246,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ deregistered the CRQ. - + - R1-R1--9. For the CRQ facility: The platform (transport @@ -3906,108 +4256,108 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ bytes in all CRQ entries. - + - R1-R1--10. For the CRQ facility: The first byte of a CRQ entry - must be the Header byte and must be as defined in + must be the Header byte and must be as defined in . - + - R1-R1--11. For the CRQ facility: The Format byte (second byte) - of a Valid Initialization CRQ entry must be as defined in + of a Valid Initialization CRQ entry must be as defined in . - + - R1-R1--12. For the CRQ facility: The Format byte (second byte) - of a Valid Transport Event queue entry must be as defined in + of a Valid Transport Event queue entry must be as defined in . - + - R1-R1--13. For the CRQ facility: If the partner partition fails, then the platform must enqueue a 16 byte entry starting with 0xFF01 (last - 14 bytes unspecified) as specified in Requirement + 14 bytes unspecified) as specified in Requirement except as required by - Requirements - and + Requirements + and . - + - R1-R1--14. For the CRQ facility: If the partner partition deregisters its corresponding CRQ, then the platform must enqueue a 16 byte entry starting with 0xFF02 (last 14 bytes unspecified) as specified - in Requirement + in Requirement except as required by - Requirements - and + Requirements + and . - + - R1-R1--15. Reserved - + - R1-R1--16. For the CRQ facility with the Partner Control option: If the partner partition is terminated by request of - this partition via the + this partition via the ibm,partner-control RTAS call, then the platform must enqueue a 16 byte entry starting with 0xFF04 (last 14 bytes unspecified) - as specified in Requirement + as specified in Requirement except as required by - Requirements - and + Requirements + and when the partner partition has been successfully terminated. - + - R1-R1--17. Reserved - + - R1-R1--18. For the CRQ facility option: Platforms that implement @@ -4015,9 +4365,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ for use by the CRQ. - + - R1-R1--19. For the CRQ facility: The platforms must emulate the @@ -4027,9 +4377,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ appropriate for CRQ interrupts. - + - R1-R1--20. For the CRQ facility: The platform’s OF must @@ -4037,9 +4387,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ control to the booted partition program. - + - R1-R1--21. For the CRQ facility: The platform’s OF must @@ -4047,9 +4397,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ IOA’s CRQ. - + - R1-R1--22. For the CRQ facility: The platform’s OF must @@ -4057,9 +4407,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ IOA’s CRQ. - + - R1-R1--23. For the CRQ facility: The platform must present (as @@ -4072,9 +4422,9 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ source number is still outstanding. - + - R1-R1--24. For the CRQ facility: The platform must not present @@ -4094,7 +4444,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ H_PUT_RTCE_INDIRECT) A server partition uses the hypervisor function, H_PUT_RTCE, which takes as a parameter the opaque handle (LIOBN) of the partner - partition’s RTCE table (second window pane of + partition’s RTCE table (second window pane of “ibm,my-dma-window”), an offset in the RTCE table, the handle for one of the server partition's I/O adapter TCE tables plus an offset within the I/O adapter's TCE table. H_PUT_RTCE then @@ -4120,7 +4470,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ rules are acceptable. The architectural intent is to provide RDMA performance essentially equivalent to direct TCE operations. - + The partner partition's RTCE table is itself never directly accessed by an I/O Adapter (IOA), it is only accessed by the hypervisor, @@ -4153,22 +4503,22 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ - A server partition is guaranteed that it can create one redirected + A server partition is guaranteed that it can create one redirected mapping per RTCE table entry. By default if the - server partition tries to create another copy of the same RTCE table TCE + server partition tries to create another copy of the same RTCE table TCE it gets an error return. Platforms that support - the H_VIOCTL hcall() might support multiple redirected + the H_VIOCTL hcall() might support multiple redirected RTCE table mappings provided that they do not duplicate - existing mappings (the mappings are for different I/O operations); + existing mappings (the mappings are for different I/O operations); if they do, the total number of such multiple mappings per LIOBN and per RTCE page is communicated by the “GET_MAX_REDIRECTED_MAPPINGS” sub-function of the H_VIOCTL hcall(). If the - “GET_MAX_REDIRECTED_MAPPINGS” sub-function of the + “GET_MAX_REDIRECTED_MAPPINGS” sub-function of the H_VIOCTL hcall() is not implemented then only the default single copy is supported. - Multiple mappings + Multiple mappings of the same physical page are always allowed, as - long as they originate from different RTCE table TCEs + long as they originate from different RTCE table TCEs just like with physical IOA TCEs. @@ -4182,7 +4532,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ partition’s errors from corrupting another partition’s state. - + The RTCE table TCE is not currently in use: Clear/invalidate the TCE copy pointer and enter the RTCE table TCE mapping per the input @@ -4218,12 +4568,12 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ resources in the face of errors. Therefore, the server partition’s TCE is considered invalid, but the server partition may or may not be able to immediately invalidate the TCEs. For more information on - invalidation of TCEs, see + invalidation of TCEs, see . The H_Resource return from an H_PUT_TCE, H_PUT_TCE_INDIRECT, and H_STUFF_TCE may be used to hold off invalidation in this case. - + @@ -4236,7 +4586,7 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ - The server partition may use any of the supported hcall()s (see + The server partition may use any of the supported hcall()s (see ) to manage the TCE tables used by its IOAs. No extra restrictions are made to changes of the server partition's TCE table beside those stated in 2 above. The server @@ -4266,13 +4616,13 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */ TCE and reject the call if the LMB did not belong to the requester. - +
H_PUT_RTCE This hcall() maps “count” number of contiguous TCEs in an RTCE to the same number of contiguous IOA TCEs. The H_REMOVE_RTCE - hcall() is used to back-out TCEs built with H_PUT_RTCE hcall(). + hcall() is used to back-out TCEs built with H_PUT_RTCE hcall(). for that hcall(). @@ -4301,132 +4651,132 @@ hcall ( const uint64 H_PUT_RTCE, /* Maps RDMA into IOA’s TCE table */ );]]> - + Parameters: - + r-liobn: Handle of RDMA RTCE table - + r-ioba: IO address per RDMA RTCE table - + liobn: Logical I/O Bus Number of server TCE table - + ioba: I/O address as seen by server IOA - + count: Number of consecutive 4 KB pages to map - + - + Semantics: - + Validates r-liobn is from the second triple (second window pane) - of the server partition’s + of the server partition’s “ibm,my-dma-window” property, else return H_Parameter. - + Validates r-ioba plus (count * 4 KB) is within range of RTCE table as specified by the window pane as specified by the r-liobn, else return H_Parameter. - + Validates that the TCE table associated with liobn is owned by calling partition, else return H_Parameter. - + If the Shared Logical Resource option is implemented and the LIOBN, represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + Validates that ioba plus (count * 4 KB) is within the range of TCE table specified by liobn, else return H_Parameter. - + If the Shared Logical Resource option is implemented and the IOBA represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + For count entries - + The following is done in a critical section with respect to updates to the r-ioba entry of the RTCE table TCE - + Check that the r-ioba entry of the RTCE table contains a valid mapping (this requires having a completed partner connection), else return H_R_Parm with the value of the loop count in R4. - + - Prevent more redirected mappings of the same r-ioba than + Prevent more redirected mappings of the same r-ioba than the platform supports and/or duplicates: If the r-ioba - entry of the RTCE table TCE contains a valid pointer, and + entry of the RTCE table TCE contains a valid pointer, and if that pointer references a TCE that is a clone of the - r-ioba entry of the RTCE table TCE, then an additional + r-ioba entry of the RTCE table TCE, then an additional redirected mapping, if supported, is used else return H_Resource with the value of the loop count in R4. - + - Validate the liobn and ioba are not already mapped for + Validate the liobn and ioba are not already mapped for this entry else return H_IN_USE with the value of the loop count in R4. - + - Validate the number of redirected mappings for the - r-ioba does not exceed the + Validate the number of redirected mappings for the + r-ioba does not exceed the “ibm,max-rtce-mappings” - value for any of the adapters mapped by the RTCE else + value for any of the adapters mapped by the RTCE else return H_Resource with the value of the loop count in R4. - + - Validate the number of redirected mappings for the r-ioba + Validate the number of redirected mappings for the r-ioba does not exceed the per client IOBA value returned - from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function + from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function else return H_Resource with the value of the loop count in R4. - + - Validate the new entry will not cause the number of + Validate the new entry will not cause the number of additional redirected mappings that have already been made for this r-liobn to exceed the maximum retrieved by the H_VIOCTL - GET_MAX_REDIRECTED_MAPPINGS sub-function else return + GET_MAX_REDIRECTED_MAPPINGS sub-function else return H_Resource with the value of the loop count in R4. - + Copy the DMA address mapping from the r-ioba entry of the r-liobn RTCE table to the ioba entry of the liobn TCE table and save a pointer to @@ -4434,20 +4784,20 @@ hcall ( const uint64 H_PUT_RTCE, /* Maps RDMA into IOA’s TCE table */ RTCE table, or in a separate structure associated with the r-liobn RTCE table. - + End Loop (The critical section lasts for one iteration of the loop) - + - + Return H_Success - + Implementation Note: The PA requires the OS to issue a sync instruction to proceed the signalling of an IOA to start an IO operation @@ -4467,7 +4817,7 @@ hcall ( const uint64 H_PUT_RTCE, /* Maps RDMA into IOA’s TCE table */ This hcall() maps “count” number of potentially non-contiguous TCEs in an RTCE to the same number of contiguous IOA TCEs. The H_REMOVE_RTCE hcall() is used to back-out TCEs built with the - H_PUT_RTCE_INDIRECT hcall(). + H_PUT_RTCE_INDIRECT hcall(). for that hcall(). @@ -4501,103 +4851,103 @@ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ );]]> - + Parameters: - + buff-addr: The Logical Address of a page (4 KB, 4 KB boundary) containing a list of r-ioba to be mapped via using the r-liobn RTCE table - + r-liobn: Handle of RTCE table to be used with r-ioba entries in - indirect buffer (second window pane from server + indirect buffer (second window pane from server “ibm,my-dma-window” - + liobn: Logical I/O Bus Number of server TCE table - + ioba: I/O address as seen by server IOA - + count: Number of consecutive IOA bus 4 KB pages to map (number of entries in buffer) - + - + Semantics: - + Validates r-liobn is from the second triple (second window pane) - of the server partition’s + of the server partition’s “ibm,my-dma-window” property, else return H_Parameter. - + Validates buff-addr points to the beginning of a 4 KB page owned by the calling partition, else return H_Parameter. - + If the Shared Logical Resource option is implemented and the logical address’s page number represents a page that has been rescinded by the owner, return H_RESCINDED. - + - + Validates that the TCE table associated with liobn is owned by calling partition, else return H_Parameter. - + If the Shared Logical Resource option is implemented and the LIOBN represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + Validates that ioba plus (count * 4 KB) is within the range of TCE table specified by liobn, else return H_Parameter. - + If the Shared Logical Resource option is implemented and the IOBA represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + If the count field is greater than 512 return H_Parameter. - + Copy (count * 8) bytes from the page specified by buff-addr to a temporary hypervisor page for contents verification and processing (this avoids the problem of the caller changing call by reference values after they are checked). - + For count entries: - + Validate the r-ioba entry in the temporary page is within range of RTCE table as specified by r-liobn, else place the count number in R4 @@ -4607,19 +4957,19 @@ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ End loop - + - + For count validated entries in the hypervisor's temporary page: - + The following is done in a critical section with respect to updates to the r-ioba entry of the RTCE - + Check that the r-ioba entry of the r-liobn RTCE table contains a valid mapping (this requires having a completed partner connection), else @@ -4627,41 +4977,41 @@ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ - Prevent more redirected mappings of the same r-ioba than + Prevent more redirected mappings of the same r-ioba than the platform supports and/or duplicates: If the r-ioba - entry of the RTCE table TCE contains a valid pointer, and + entry of the RTCE table TCE contains a valid pointer, and if that pointer references a TCE that is a clone of the - r-ioba entry of the RTCE table TCE, then an additional + r-ioba entry of the RTCE table TCE, then an additional redirected mapping, if supported, is used else return H_Resource with the value of the loop count in R4. - + - Validate the liobn and ioba are not already mapped for + Validate the liobn and ioba are not already mapped for this entry else return H_IN_USE with the value of the loop count in R4. - + - Validate the number of redirected mappings for the - r-ioba does not exceed the + Validate the number of redirected mappings for the + r-ioba does not exceed the “ibm,max-rtce-mappings” - value for any of the adapters mapped by the RTCE else + value for any of the adapters mapped by the RTCE else return H_Resource with the value of the loop count in R4. - + - Validate the number of redirected mappings for the r-ioba + Validate the number of redirected mappings for the r-ioba does not exceed the per client IOBA value returned - from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function + from the H_VIOCTL GET_MAX_REDIRECTED_MAPPINGS sub-function else return H_Resource with the value of the loop count in R4. - + - Validate the new entry will not cause the number of + Validate the new entry will not cause the number of additional redirected mappings that have already been made for this r-liobn to exceed the maximum retrieved by the H_VIOCTL - GET_MAX_REDIRECTED_MAPPINGS sub-function else return + GET_MAX_REDIRECTED_MAPPINGS sub-function else return H_Resource with the value of the loop count in R4. @@ -4674,20 +5024,20 @@ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ RTCE table, or into a separate structure associated with the r-liobn RTCE table. - + End Loop (The critical section lasts for one iteration of the loop) - + - + Return H_Success - + Implementation Note: The PA requires the OS to issue a sync instruction to proceed the signalling of an IOA to start an IO @@ -4701,7 +5051,7 @@ hcall ( const uint64 H_PUT_RTCE_INDIRECT, /* Maps RDMA into IOA’s TCE table */ Excessive size of the count parameter may cause an extended delay.
- +
H_REMOVE_RTCE The H_REMOVE_RTCE hcall() is used to back-out TCEs built with @@ -4731,91 +5081,91 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ );]]> - + Parameters: - + r-liobn: Handle of RDMA RTCE table - + r-ioba: IO address per RDMA RTCE table - + liobn: Logical I/O Bus Number of server TCE table - + ioba: I/O address as seen by server IOA - + count: Number of consecutive 4 KB pages to unmap - + tce-value: TCE value to be put into the IOA TCE(s) after setting the “Page Mapping and Control” bits to “Page fault (no access)”. - + - + Semantics: - + Validates r-liobn is from the second triple (second window pane) - of the server partition’s + of the server partition’s “ibm,my-dma-window” property, else return H_Parameter. - + Validates r-ioba plus (count * 4 KB) is within range of RTCE table as specified by the window pane as specified by the r-liobn, else return H_Parameter. - + Validates that the TCE table associated with liobn is owned by calling partition, else return H_Parameter. - + If the Shared Logical Resource option is implemented and the LIOBN, represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + Validates that ioba plus (count * 4 KB) is within the range of TCE table specified by liobn, else return H_Parameter. - + If the Shared Logical Resource option is implemented and the IOBA represents a logical resource that has been rescinded by the owner, return H_RESCINDED. - + - + For count entries - + The following is done in a critical section with respect to updates the r-ioba entry of the RTCE table TCE - + If it exists, invalidate the pointer in the r-ioba entry of the r-liobn RTCE table (or in a separate structure associated with the @@ -4827,20 +5177,20 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ after setting the “Page Mapping and Control” bits to “Page fault (no access)”. - + End Loop (The critical section lasts for one iteration of the loop) - + - + Return H_Success - + Implementation Note: The execution time for this hcall() is expected to be a linear function of the count parameter. Excessive size @@ -4854,31 +5204,31 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ attempt to unmap a TCE in an IOA’s TCE table prior to the completion of the operation which setup the TCE. For example: - + A client attempts to H_PUT_TCE to its DMA window pane, which is mapped to the second window pane of the server’s DMA window, and the TCE in the RTCE table which is the target of the H_PUT_TCE already points to a valid TCE in an IOA’s TCE table. - + A client attempts to H_FREE_CRQ and the server’s second window pane for that virtual IOA contains a TCE which points to a valid TCE in an IOA’s TCE table. - + A client partition attempts to reboot (which essentially is an H_FREE_CRQ). - + A server attempts to H_FREE_CRQ and the server’s second window pane for that virtual IOA contains a TCE which points to a valid TCE in an IOA’s TCE table. - + In such error and error recovery situations, the hypervisor attempts to prevent the changing of an IOAs TCE to a value that would @@ -4890,23 +5240,23 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ to read, while DMA writes (which were for a defunct operation) are silently dropped. This works well when all the following are true: - + The platform supports separate TCE read and write enable bits in the TCE - + EEH is enabled and the DD can recover from the MMIO Stopped and DMA Stopped states - + The IOA and the IOA’s DD can recover gracefully from Target Aborts (which are received on a read to a page where the read enable bit is off) - + If these conditions are not true then the hypervisor will need to try to prevent or delay invalidation of the TCEs. The H_Resource return @@ -4915,8 +5265,8 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ complete the operation and the server can invalidate the IOA’s TCE. In addition, the Bit Bucket Allowed LIOBN attribute and the H_LIOBN_ATTRIBUTES hcall can be used to help enhance the recoverability - in these error scenarios (see - and + in these error scenarios (see + and for more information).
@@ -4924,8 +5274,8 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ LIOBN Attributes There are certain LIOBN attributes that are made visible to and can be manipulated by partition software. The H_LIOBN_ATTRIBUTES hcall is - used to read and modify the attributes (see - ). + used to read and modify the attributes (see + ). defines the attributes that are visible and manipulatable.   @@ -4989,7 +5339,7 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ in-flight DMA does not cause a non-recoverable error. Software Implementation Notes: - + The results of changing this field when there are valid TCEs for the LIOBN may produce unexpected results. The @@ -5005,7 +5355,7 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ H_LIOBN_ATTRIBUTES hcall() regardless, with a status of H_Constrained if not changeable). - + @@ -5019,20 +5369,20 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ - R1-R1--1. If the H_LIOBN_ATTRIBUTES hcall is implemented, then it must implement the attributes as they are defined in - + and the syntax and semantics as - defined in + defined in . - + - R1-R1--2. The H_LIOBN_ATTRIBUTES hcall must @@ -5044,7 +5394,7 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ - + A value of 0 for unimplemented bit positions. @@ -5052,7 +5402,7 @@ hcall ( const uint64 H_REMOVE_RTCE, /* Unmaps RDMA from IOA’s TCE table */ The resultant field values for implemented fields. - + Syntax: @@ -5078,7 +5428,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ performed. reset-mask: The bit-significant mask of bits to be reset in the LIOBN’s Attributes (the reset-mask bit definition aligns with the - bit definition of the LIOBN’s Attributes, as defined in + bit definition of the LIOBN’s Attributes, as defined in ). The complement of the reset-mask is ANDed with the LIOBN’s Attributes, prior to applying the set-mask. See semantics for more details on any field-specific @@ -5087,7 +5437,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ corresponding bit(s) in the reset-mask are ignored. set-mask: The bit-significant mask of bits to be set in the LIOBN’s Attributes (the set-mask bit definition aligns with the bit - definition of the LIOBN’s Attributes, as defined in + definition of the LIOBN’s Attributes, as defined in ). The set-mask is ORed with the LIOBN’s Attributes, after to applying the reset-mask. See semantics for more details on any field-specific actions needed during @@ -5099,12 +5449,12 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ Semantics: - + Validate that liobn belongs to the partition, else H_Parameter. - + If the Bit Bucket Allowed field of the specified LIOBN’s Attributes is implemented and changeable, then set it to the result @@ -5113,13 +5463,13 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ corresponding bits of the reset-mask and then ORed with the corresponding bits of the set-mask. - + Load R4 with the value of the LIOBN’s Attributes, with any unimplemented bits set to 0, and if all requested changes were made, then return H_Success, otherwise return H_Constrained. - + @@ -5131,8 +5481,8 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */
H_PUT_TCE, H_PUT_TCE_INDIRECT, and H_STUFF_TCE - These hcall()s are only valid for the first window pane of the - “ibm,my-dma-window” property. See + These hcall()s are only valid for the first window pane of the + “ibm,my-dma-window” property. See for information about window pane types. The following are extensions that apply to the H_PUT_TCE, @@ -5142,53 +5492,53 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ H-Parameter) LIOBN as referring to a RTCE table (first window pane) and access accordingly: - + If the TCE is not from the first triple (first window pane) of - the calling partition’s + the calling partition’s “ibm,my-dma-window” property, return H_Parameter. - + If the TCE is not currently in use: Clear/invalidate the TCE copy pointer and enter the TCE mapping per the input parameters to the hcall(). - + If the TCE contains a valid mapping and the TCE copy pointer is invalid: Enter the TCE mapping per the input parameters to the hcall(). - + If the TCE contains a valid mapping and the TCE copy pointer references a TCE that does not contain a valid copy of the previous mapping in the TCE: Clear/invalidate the TCE copy pointer and enter the TCE mapping per the input parameters to the hcall(). - + If the TCE contains a valid mapping and the TCE copy pointer references a TCE that does contain a valid copy of the previous mapping in the TCE, then: - + If the Bit Bucket Allowed Attribute of the LIOBN containing the TCE is a 1, invalidate the copied TCE and enter the TCE mapping per the input parameters to the hcall(). - + If the Bit Bucket Allowed Attribute of the LIOBN containing the TCE is a 0, then return H_Resource or perform some other platform-specific error recovery. - + - +
@@ -5216,41 +5566,41 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ Subordinate Command/Response Queue (Sub-CRQ) The Sub-CRQ facility is used in conjunction with the CRQ facility, for some virtual IOA types, when more than one queue is needed for the - virtual IOA. For information on the CRQ facility, see + virtual IOA. For information on the CRQ facility, see . For information on which virtual IOAs may use the Sub-CRQ facilities, see the applicable sections - for the virtual IOAs. See + for the virtual IOAs. See for a comparison of the differences in the queue structures between CRQs and Sub-CRQs. In - addition to the hcall()s specified in + addition to the hcall()s specified in , all of the following hcall()s and RTAS calls are applicable to both CRQs and Sub-CRQs: - + H_XIRR - + H_EOI - + ibm,int-on - + ibm,int-off - + ibm,set-xive - + ibm,get-xive - +  
@@ -5342,7 +5692,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ Interrupt number - Obtained from + Obtained from “interrupts” property @@ -5359,7 +5709,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ H_VIOCTL subfunction For virtual IOAs that define the use of Sub-CRQs, the - interrupt associated with the CRQ, as defined by the + interrupt associated with the CRQ, as defined by the “interrupts” property in the OF device tree, may be enabled or disabled with either the H_VIOCTL or the H_VIO_SIGNAL hcall(). The CRQ interrupt @@ -5404,7 +5754,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ of 32 byte long elements. Each queue is mapped into contiguous I/O addresses via the TCE mechanism and RTCE table (first window pane). The I/O address and length of each queue is registered by the process defined - in + in . This registration process tells the hypervisor where to find the virtual IOA’s Sub-CRQ(s). @@ -5413,7 +5763,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */
Sub-CRQ Entry Format Each Sub-CRQ entry consists of a 32 byte element. The first byte of - a Sub-CRQ entry is the Header byte and is defined in + a Sub-CRQ entry is the Header byte and is defined in .  
@@ -5508,7 +5858,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ requires that there be enough space on the queue for all the entries, otherwise none of the entries are placed onto the Sub-CRQ.At the receiver’s option, it may be notified via an interrupt - when an element is enqueued to its Sub-CRQ. See + when an element is enqueued to its Sub-CRQ. See .When the receiver has finished processing a Sub-CRQ entry, it writes the header to the value 0x00 to invalidate the entry and free it @@ -5526,7 +5876,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ The receiver can set the virtual interrupt associated with its Sub-CRQ to one of two modes. These are: - + Disabled (an enqueued interrupt is not signaled). @@ -5535,7 +5885,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ Enabled (an enqueued interrupt is signaled on every enqueue). - + Note: An enqueue is considered a pulse not a level. The pulse then sets the memory element within the emulated interrupt @@ -5555,7 +5905,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ look at the header byte of the next queue entry to see if the entry is valid) after an H_EOI to prevent losing initiative. The hcall() used to enable and disable this Sub-CRQ interrupt - notification is H_VIO_SIGNAL (see + notification is H_VIO_SIGNAL (see ). @@ -5589,18 +5939,18 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ - R1-R1--1. For the Sub-CRQ facility: The platform must implement - the Sub-CRQ as specified in + the Sub-CRQ as specified in . - + - R1-R1--2. @@ -5611,9 +5961,9 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ entry being 32 byte aligned. - + - R1-R1--3. @@ -5623,20 +5973,20 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ contains 0x00), else the enqueue operation fails. - + - R1-R1--4. For the Sub-CRQ facility: The first byte of a Sub-CRQ - entry must be the Header byte and must be as defined in + entry must be the Header byte and must be as defined in . - + - R1-R1--5. @@ -5645,9 +5995,9 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ pages mapped for use by the Sub-CRQ. - + - R1-R1--6. @@ -5672,27 +6022,27 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ synchronous hcall() operations. The Synchronous VIO infrastructure defines three options: - + - Reliable Command/Response Transport option (see + Reliable Command/Response Transport option (see - + - Subordinate CRQ Transport option (see + Subordinate CRQ Transport option (see - + - Logical Remote DMA (LRDMA) option (see + Logical Remote DMA (LRDMA) option (see ) - +
Reliable Command/Response Transport Option - For the synchronous infrastructure, the CRQ facility defined in - is + For the synchronous infrastructure, the CRQ facility defined in + is implemented via the Reliable Command/Response Transport option. The synchronous nature of this infrastructure allows for the capability to immediately (synchronously) notify the sender of the @@ -5700,16 +6050,16 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */
Reliable CRQ Format and Registration - The format of the CRQ is as defined in + The format of the CRQ is as defined in . The I/O address and length of the queue are registered using the - H_REG_CRQ hcall(). + H_REG_CRQ hcall(). .
Reliable CRQ Entry Format - See + See .
@@ -5717,7 +6067,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ Reliable CRQ Entry Processing A sender uses the H_SEND_CRQ hcall() to enter a 16 byte message on its partner’s queue. The hcall() takes the entire message as input - parameters in two registers. + parameters in two registers. .
@@ -5725,7 +6075,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ Reliable Command/Response Transport Interrupt Notification The receiver can enable and disable the virtual interrupt - associated with its CRQ. See + associated with its CRQ. See . @@ -5740,26 +6090,26 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ architecturally with this connection process (the design of an implementation may preclude some of these conditions). - + The association connection to the partner virtual IOA not being defined (H_Not_Found). The CRQ registration function fails if the CRQ is not registered with the hypervisor. - + The partner virtual IOA may not have registered its CRQ (H_Closed). The CRQ is registered with the hypervisor and the connection. However, the connection is incomplete because their partner has not registered. - + The partner virtual IOA may be already connected to another partner virtual IOA (H_Resource). The CRQ registration function fails if the CRQ is not registered with the hypervisor or the connection. - + The reaction of the virtual IOA device driver to these conditions is somewhat different depending upon the calling device driver being for @@ -5786,7 +6136,7 @@ hcall ( const uint64 H_LIOBN_ATTRIBUTES, /* Returns in R4 the resulting LIOBN */ of the server partition. This association is dropped when either partner deregisters or terminates. However, on deregistration or termination, the RTCE tables associated with the local partition (first window pane) - remain intact for that partition (see Requirement + remain intact for that partition (see Requirement ).
@@ -5813,69 +6163,69 @@ hcall ( const int64 H_REG_CRQ, /* Function Code */ Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property - + queue: I/O address (offset into the RTCE table) of the CRQ buffer (starting on a 4 KB boundary). - + len: Length of the CRQ in bytes (a multiple of 4 KB) - + Semantics: - + Validate unit-address, else H_Parameter - + Validate queue, which is the I/O address of the CRQ (I/O addresses for entire buffer length starting at the specified I/O address are translated by the RTCE table, is 4 KB aligned, and length, len, is a multiple of 4 KB), else H_Parameter - + Validate that there is an authorized connection to another partition associated with the Unit Address, else H_Not_Found. - + Validate that the authorized connection to another partition associated with the Unit Address is free, else H_Resource. - + Initialize the CRQ enqueue pointer and length variables. These variables are kept in terms of I/O addresses so that page migration works and any remapping of TCEs is effective. - + Disable CRQ interrupts. - + Allow for Logical Remote DMA, when applicable, with associated partner partition when partner registers. - + If partner is already registered, then return H_Success, else return H_Closed. - +
@@ -5899,58 +6249,58 @@ hcall ( const int64 H_FREE_CRQ, /* Function Code */ Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property - + Semantics: - + Validate unit-address, else H_Parameter - + Mark the connection to the associated partner partition as closed (so that send hcall()s from the partner partition fail). - + Mark the CRQ enqueue pointer and length variables as invalid. - + For any and all Sub-CRQs associated with the CRQ, do the following: - + Mark the connection to the associated partner partition as closed for the Sub-CRQ (so that send hcall()s from the partner partition fail). - + Mark the Sub-CRQ enqueue pointer and length variables for the Sub-CRQ as invalid. - + Disable Sub-CRQ interrupts for the Sub-CRQ. - + - + Disable CRQ interrupts. - + If there exists any Redirected TCEs in the local TCE tables associated with this Virtual IOA, and all of those tables have a Bit @@ -5959,24 +6309,24 @@ hcall ( const int64 H_FREE_CRQ, /* Function Code */ TCEs in the local TCE tables (for information on invalidation of TCEs, see ). - + If there exists any Redirected TCEs in the local TCE tables associated with this Virtual IOA, and any of those tables have a Bit Bucket Allowed attribute of 0, then return H_Resource or perform some other platform-specific error recovery. - + Send partner terminated message to partner queue (if it is still registered), overlaying the last valid entry in the queue if the CRQ is full. - + Return H_Success. - + Implementation Note: If the hypervisor returns an H_Busy, H_LongBusyOrder1mSec, or H_LongBusyOrder10mSec, software must @@ -6010,91 +6360,91 @@ hcall ( const int64 H_SEND_CRQ, /* Function Code */ Parameters: - + - unit-addr: Unit Address per device tree node + unit-addr: Unit Address per device tree node “reg” property - + msg-high: - + header: high order bit is on -- header of value 0xFF is reserved for transport error and is invalid for input. - + format: not checked by the firmware. - + - + msg-low: not checked by the firmware -- should be consistent with the definition of the format byte. - + Semantics: - + Validate the Unit Address, else return H_Parameter - + Validate that the msg header byte has its high order bit on and that it is not = 0xFF, else return H_Parameter. - + Validate that there is an authorized connection to another partition associated with the Unit Address and that the associated CRQ is enabled, else return H_Closed. - + Enter Critical Section on target CRQ - + Validate that there is room on the receive queue for the message and allocate that message, else exit critical Section and return H_Dropped. - + Store msg-low into the second 8 bytes of the allocated queue element. - + Store order barrier - + Store msg-high into the first 8 bytes of the allocated queue element (setting the header valid bit.) - + - + Exit Critical Section - + If receiver queue interrupt mode == enabled, then signal interrupt - + Return H_Success. - + @@ -6103,7 +6453,7 @@ hcall ( const int64 H_SEND_CRQ, /* Function Code */ This hcall() explicitly enables a CRQ that has been disabled due to a Partner partition suspended transport event. As a side effect of this hcall(), all pages that are mapped via the logical TCE table associated - with the first pane of + with the first pane of “ibm,my-dma-window” property of the associated virtual IOA are restored prior to successful completion of the hcall(). It is the architectural intent that this hcall() is made while @@ -6131,39 +6481,39 @@ hcall ( const int64 H_ENABLE_CRQ, /* Function Code */ Parameters: - + - unit-addr: Unit Address per device tree node + unit-addr: Unit Address per device tree node “reg” property - + Semantics: - + Validate the Unit Address, else return H_Parameter - + Test that all pages mapped through the logical TCE table - associated with the first pane of the + associated with the first pane of the “ibm,my-dma-window” property associated with the unit-address parameter are present; else return H_LongBusyOrder10mSec. - + Set the status of the CRQ associated with the unit-address parameter to enabled. - + Return H_Success. - + @@ -6174,57 +6524,57 @@ hcall ( const int64 H_ENABLE_CRQ, /* Function Code */ - R1-R1--1. For the Reliable Command/Response Transport option: The platform must implement the CRQ facility, as - defined in + defined in . - + - R1-R1--2. For the Reliable Command/Response Transport - option: The platform must implement the H_REG_CRQ hcall(). + option: The platform must implement the H_REG_CRQ hcall(). . - R1-R1--3. For the Reliable Command/Response Transport - option: The platform must implement the H_FREE_CRQ hcall(). + option: The platform must implement the H_FREE_CRQ hcall(). . - R1-R1--4. For the Reliable Command/Response Transport - option: The platform must implement the H_SEND_CRQ hcall(). + option: The platform must implement the H_SEND_CRQ hcall(). . - R1-R1--5. For the Reliable Command/Response Transport - option: The platform must implement the H_ENABLE_CRQ hcall(). + option: The platform must implement the H_ENABLE_CRQ hcall(). . @@ -6239,35 +6589,35 @@ hcall ( const int64 H_ENABLE_CRQ, /* Function Code */ partition for VIO operations. This architecture defines two modes of RDMA - + Copy RDMA is used to have the hypervisor copy data between a buffer in the server partition’s memory and a buffer in - the partner partition’s memory. See + the partner partition’s memory. See for more information on Copy RDMA with respect to LRDMA. - + Redirected RDMA allows for a server partition to securely target its I/O adapter's DMA operations directly at the memory pages of the partner partition. The platform overhead of Copy RDMA is generally greater than Redirected RDMA, but this overhead may be offset if the server partition’s DMA buffer is being used as a data cache - for multiple VIO operations. See + for multiple VIO operations. See for more information on Redirected RDMA with respect to LRDMA. - + The mapping between the LIOBN in the second pane of a server - virtual IOA’s + virtual IOA’s “ibm,my-dma-window” property and the corresponding partner IOA’s RTCE table is made when the CRQ successfully completes registration. The partner partition is not aware if the server partition is using Copy RDMA or Redirected RDMA. The server partition uses the Logical RDMA mode that best suits its needs for a - given VIO operation. See + given VIO operation. See for more information on RTCE tables. @@ -6284,9 +6634,9 @@ hcall ( const int64 H_ENABLE_CRQ, /* Function Code */ This hcall() copies data from an RTCE table mapped buffer in one partition to an RTCE table mapped buffer in another partition, with the length of the transfer being specified by the transfer length parameter - in the hcall(). The + in the hcall(). The “ibm,max-virtual-dma-size” property, if - it exists (in the + it exists (in the /vdevice (node), specifies the maximum length of the transfer (minimum value of this property is 128 KB). @@ -6308,74 +6658,74 @@ hcall ( const uint64 H_COPY_RDMA, /* Performs Copy RDMA */ Parameters: - + - len: Length of transfer (length not to exceed the value in the + len: Length of transfer (length not to exceed the value in the “ibm,max-virtual-dma-size” property, if it exists) - + s-liobn: LIOBN (RTCE table handle) of V-DMA source buffer - + s-ioba: IO address of V-DMA source buffer - + d-liobn: LIOBN (RTCE table handle) of V-DMA destination buffer - + d-ioba: I/O address of V-DMA destination buffer - + Semantics: - + Serialize access to RTCE tables with H_MIGRATE_DMA. - + - If the + If the “ibm,max-virtual-dma-size” property exist - in the + in the /vdevice node of the device tree, then if the value of len is greater than the value of this property, return H_Parameter. - + Source and destination LIOBNs are checked for authorization per - the + the “ibm,my-dma-window” property, else return H_S_Parm or H_D_Parm, respectively. - + Source and destination ioba’s and length are checked for - valid ranges per the + valid ranges per the “ibm,my-dma-window” property, else return H_S_Parm or H_D_Parm, respectively. - + The access bits of the associated TCEs are checked for authorization, else return H_Permission. - + Copy len number of bytes from the buffer starting at the specified source address to the buffer starting at the specified destination address, then return H_Success. - + @@ -6406,86 +6756,86 @@ hcall ( const uint64 H_WRITE_RDMA, /* Performs Copy RDMA */ Parameters: - + len: Length of transfer - + d-liobn: LIOBN (RTCE table handle) of V-DMA destination buffer - + d-ioba: I/O address of V-DMA destination buffer - + data1: Source data - + data2: Source data - + data3: Source data - + data4: Source data - + data5: Source data - + data6: Source data - + Semantics: - + Check that the len parameter => 0 and <= 48, else return H_Parameter - + The destination LIOBN is checked for authorization per the remote - triple of the one of the calling partition’s + triple of the one of the calling partition’s “ibm,my-dma-window” property, else return H_D_Parm. - + The destination ioba and length are check for valid ranges per - the remote triple of the one of the calling partition’s + the remote triple of the one of the calling partition’s “ibm,my-dma-window” property, else return H_D_Parm. - + Serialize access to the destination RTCE table with H_MIGRATE_DMA. - + The access bits of the associated RTCE table TCEs are checked for authorization, else return H_Permission. - + Copy len number of bytes from the data parameters starting at the high order byte of data1 toward the low order byte of data 6 into the buffer starting at the specified destination address, then return H_Success. - + @@ -6510,61 +6860,61 @@ hcall ( const uint64 H_READ_RDMA, /* Performs Copy RDMA */ Parameters: - + len: Length of transfer - + s-liobn: LIOBN (RTCE table handle) of V-DMA source buffer - + s-ioba: IO address of V-DMA source buffer - + Semantics: - + Check that the len parameter => 0 and <= 72, else return H_Parameter - + The source LIOBN is checked for authorization per the remote - triple of the one of the calling partition’s + triple of the one of the calling partition’s “ibm,my-dma-window” property, else return H_S_Parm. - + The source ioba and length are check for valid ranges per the - remote triple of the one of the calling partition’s + remote triple of the one of the calling partition’s “ibm,my-dma-window” property, else return H_S_Parm. - + Serialize access to the source RTCE table with H_MIGRATE_DMA. - + The access bits of the associated RTCE table TCEs are checked for authorization, else return H_Permission. - + Copy len number of bytes from the source data buffer specified by s-liobn starting at s-ioba, into the registers R4 through R12 starting with the high order byte of R4 toward the low order byte of R12, then return H_Success. - + @@ -6574,51 +6924,51 @@ hcall ( const uint64 H_READ_RDMA, /* Performs Copy RDMA */ - R1-R1--1. For the Logical Remote DMA option: The platform must - implement the H_PUT_RTCE hcall() as specified in + implement the H_PUT_RTCE hcall() as specified in . - + - R1-R1--2. For the Logical Remote DMA option: The platform must - implement the extensions to the H_PUT_TCE hcall() as specified in + implement the extensions to the H_PUT_TCE hcall() as specified in . - + - R1-R1--3. For the Logical Remote DMA option: The platform must - implement the extensions to the H_MIGRATE_DMA hcall() as specified in + implement the extensions to the H_MIGRATE_DMA hcall() as specified in . - + - R1-R1--4. For the Logical Remote DMA option: The platform must - implement the H_COPY_RDMA hcall() as specified in + implement the H_COPY_RDMA hcall() as specified in . - + - R1-R1--5. @@ -6633,10 +6983,10 @@ hcall ( const uint64 H_READ_RDMA, /* Performs Copy RDMA */ Implementation Note: It is expected that as part of - meeting Requirement + meeting Requirement , all of the terminating partition’s TCE table entries (regular and RTCE) are invalidated - along with any clones (for information on invalidation of TCEs, see + along with any clones (for information on invalidation of TCEs, see ). While other mechanisms are available for meeting this requirement in the case of H_COPY_RDMA, this is the only method for Redirected RDMA, and since it works in both cases, @@ -6648,36 +6998,36 @@ hcall ( const uint64 H_READ_RDMA, /* Performs Copy RDMA */
Subordinate CRQ Transport Option For the synchronous infrastructure, in addition to the CRQ facility - defined in - , + defined in + , the Subordinate CRQ Transport option may also be implemented in conjunction with the CRQ facility. That is, the Subordinate CRQ Transport option requires that the Reliable Command/Response Transport option also be implemented. For this option, the Sub-CRQ facility defined - in - is + in + is implemented.
Sub-CRQ Format and Registration - The format of the Sub-CRQ is as defined in + The format of the Sub-CRQ is as defined in . The I/O address and length of the queue are registered using the - H_REG_SUB_CRQ hcall(). + H_REG_SUB_CRQ hcall(). .
Sub-CRQ Entry Format - See + See .
Sub-CRQ Entry Processing A sender uses the H_SEND_SUB_CRQ or H_SEND_SUB_CRQ_INDIRECT hcall() - to enter one or more 32 byte messages on its partner’s queue. - and + to enter one or more 32 byte messages on its partner’s queue. + and .
@@ -6685,7 +7035,7 @@ hcall ( const uint64 H_READ_RDMA, /* Performs Copy RDMA */ Sub-CRQ Transport Interrupt Notification The receiver can enable and disable the virtual interrupt associated with its Sub-CRQ using the H_VIOCTL hcall(), with the - appropriate subfunction. See + appropriate subfunction. See . The interrupt number that is used in the H_VIOCTL call is obtained from the H_REG_SUB_CRQ call that is made to register the Sub-CRQ. @@ -6703,22 +7053,22 @@ hcall ( const uint64 H_READ_RDMA, /* Performs Copy RDMA */ (the design of an implementation may preclude some of these conditions). - + The association connection to the partner virtual IOA not being defined (H_Not_Found). - + The partner virtual IOA CRQ connection may not have been completed (H_Closed). - + The partner may deregister its CRQ which also deregisters any associated Sub-CRQs. - +
H_REG_SUB_CRQ @@ -6759,76 +7109,76 @@ hcall ( const int64 H_REG_SUB_CRQ, /* Returns in R4 a cookie representing */ Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property. - + Sub-CRQ-ioba: I/O address (offset into the RTCE table, as - specified by the first window pane of the virtual IOA’s + specified by the first window pane of the virtual IOA’s “ibm,my-dma-window” property) of the Sub-CRQ buffer (starting on a 4 KB boundary). - + Sub-CRQ-length: Length of the Sub-CRQ in bytes (a multiple of 4 KB). - + Semantics: - + Validate unit-address, else H_Parameter. - + Validate Sub-CRQ-ioba, which is the I/O address of the Sub-CRQ (I/O addresses for entire buffer length starting at the specified I/O address are translated by the RTCE table, is 4 KB aligned, and length, Sub-CRQ-length, is a multiple of 4 KB), else H_Parameter. - + Validate that there are sufficient resources associated with the Unit Address to allocate the Sub-CRQ, else H_Resource. - + Initialize the Sub-CRQ enqueue pointer and length variables. These variables are kept in terms of I/O addresses so that page migration works and any remapping of TCEs is effective. - + Initialize all Sub-CRQ entry header bytes to 0 (invalid). - + Disable Sub-CRQ interrupts. - + Place cookie representing Sub-CRQ number (will be used in H_SEND_SUB_CRQ, H_SEND_SUB_CRQ_INDIRECT, and H_FREE_SUB_CRQ) in R4. - + Place interrupt number (the same as will be returned by H_XIRR or H_IPOLL for the interrupt from this Sub-CRQ) in R5. - + If the CRQ connection is already complete, then return H_Success, else return H_Closed. - +
@@ -6863,46 +7213,46 @@ hcall ( const int64 H_FREE_SUB_CRQ, /* Function Code */ Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property. - + Sub-CRQ-num: The queue # cookie returned from H_REG_SUB_CRQ hcall() at queue registration time. - + Semantics: - + Validate unit-address and Sub-CRQ-num, else H_Parameter - + Mark the connection to the associated partner partition as closed for the specified Sub-CRQ (so that send hcall()s from the partner partition fail). - + Mark the Sub-CRQ enqueue pointer and length variables for the specified Sub-CRQ as invalid. - + Disable Sub-CRQ interrupts for the specified Sub-CRQ. - + Return H_Success. - +
@@ -6939,101 +7289,101 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Parameters: - + - unit-addr: Unit Address per device tree node + unit-addr: Unit Address per device tree node “reg” property. - + Sub-CRQ-num: The queue # cookie returned from H_REG_SUB_CRQ hcall() at queue registration time. - + msg-dword0: firmware checks only high order byte. - + msg-dword1, msg-dword2, msg-dword3: the rest of the message; firmware does not validate. - + Semantics: - + Validate the Unit Address, else return H_Parameter. - + Validate that the Sub-CRQ, as specified by Sub-CRQ-num, is properly registered by the partner, else return H_Parameter. - + Validate that the message header byte (high order byte of msg-dword0) is 0x80, else return H_Parameter. - + Validate that there is an authorized CRQ connection to another partition associated with the Unit Address and that the associated CRQ is enabled, else return H_Closed. - + Enter Critical Section on target Sub-CRQ. - + Validate that there is room on the specified Sub-CRQ for the message and allocate that message, else exit critical Section and return H_Dropped. - + Store msgdword1 into bytes 4-7 of the allocated queue element. - + Store msgdword2 into bytes 8-11 of the allocated queue element. - + Store msgdword3 into bytes 12-15 of the allocated queue element. - + Store order barrier. - + Store msgdword0 into bytes 0-3 of the allocated queue element (this sets the valid bit in the header byte). - + - + Exit Critical Section. - + If receiver queue interrupt mode is enabled, then signal interrupt. - + Return H_Success. - + @@ -7069,120 +7419,120 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Parameters: - + - unit-addr: Unit Address per device tree node + unit-addr: Unit Address per device tree node “reg” property. - + Sub-CRQ-num: The Sub-CRQ # cookie returned from H_REG_SUB_CRQ hcall() at queue registration time. - + ioba: The address of the TCE-mapped page which contains the entries to be placed onto the specified Sub-CRQ. - + num-entries: Number of entries to be placed onto the specified Sub-CRQ from the TCE mapped page starting at ioba (maximum number of entries is 16 in order to minimize the hcall() time). - + Semantics: - + Validate the Unit Address, else return H_Parameter. - + Validate that the Sub-CRQ, as specified by Sub-CRQ-num, is properly registered by the partner, else return H_Parameter. - + If ioba is outside of the range of the calling partition assigned values, then return H_Parameter. - + If num-entries is not in the range of 1 to 16, then return H_Parameter. - + Validate that there is an authorized CRQ connection to another partition associated with the Unit Address and that the associated CRQ is enabled, else return H_Closed. - + Copy (num-entries * 32) bytes from the page specified starting at ioba to a temporary hypervisor page for contents verification and processing (this avoids the problem of the caller changing call by reference values after they are checked). - + Validate that the message header bytes for num-entries starting at ioba are 0x80, else return H_Parameter. - + Enter Critical Section on target Sub-CRQ. - + Validate that there is room on the specified Sub-CRQ for num-entries messages and allocate those messages, else exit critical Section and return H_Dropped. - + For each of the num-entries starting at ioba - + Store entry bytes 1-31 into bytes 1-31 of the allocated queue element. - + Store order barrier. - + Store entry byte 0 into bytes 0 of the allocated queue element (this sets the valid bit in the header byte). - + Loop - + - + Exit Critical Section. - + If receiver queue interrupt mode is enabled, then signal interrupt. - + Return H_Success. - + @@ -7192,68 +7542,68 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ - R1-R1--1. For the Subordinate CRQ Transport option: The platform must implement the Reliable Command/Response Transport option, - as defined in + as defined in . - + - R1-R1--2. For the Subordinate CRQ Transport option: The - platform must implement the Sub-CRQ facility, as defined in + platform must implement the Sub-CRQ facility, as defined in . - + - R1-R1--3. For the Subordinate CRQ Transport option: The - platform must implement the H_REG_SUB_CRQ hcall(). + platform must implement the H_REG_SUB_CRQ hcall(). . - + - R1-R1--4. For the Subordinate CRQ Transport option: The - platform must implement the H_FREE_SUB_CRQ hcall(). + platform must implement the H_FREE_SUB_CRQ hcall(). . - + - R1-R1--5. For the Subordinate CRQ Transport option: The - platform must implement the H_SEND_SUB_CRQ hcall(). + platform must implement the H_SEND_SUB_CRQ hcall(). . - + - R1-R1--6. For the Subordinate CRQ Transport option: The - platform must implement the H_SEND_SUB_CRQ_INDIRECT hcall(). + platform must implement the H_SEND_SUB_CRQ_INDIRECT hcall(). . - + - R1-R1--7. For the Subordinate CRQ Transport option: The @@ -7261,19 +7611,19 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ hcall() ( ): - + DISABLE_ALL_VIO_INTERRUPTS - + DISABLE_VIO_INTERRUPT - + ENABLE_VIO_INTERRUPT - + @@ -7339,9 +7689,9 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Logical LAN IOA including any inserted VLAN header. If the port is configured for no VLAN headers, the VLAN header is removed before being delivered to the destination Logical LAN IOA. - The Logical LAN IOA’s device tree entry includes - Unit Address, and - “ibm,my-dma-window” properties. The + The Logical LAN IOA’s device tree entry includes + Unit Address, and + “ibm,my-dma-window” properties. The “ibm,my-dma-window” property contains a LIOBN field that represents the RTCE table used by the Logical IOA. The Logical LAN hcall()s use the Unit Address field to imply the LIOBN and, @@ -7382,7 +7732,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */
Logical LAN IOA Data Structures The Logical LAN IOA defines certain data structures as described in - following paragraphs. + following paragraphs. outlines the inter-relationships between several of these structures. Since multiple hcall()s as well as multiple partitions access the same structures, @@ -7433,16 +7783,16 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ the newly enqueued receive buffer descriptors have a valid bit value of 0. The hypervisor flips the value of the valid toggle bit each time it cycles from the bottom of the receive queue to the top. - Bit 5 is the Large Send Indication bit and indicates that this - packet is a large-send packet. See + Bit 5 is the Large Send Indication bit and indicates that this + packet is a large-send packet. See for more information on the usage of this bit. Bit 6 is the No Checksum bit and indicates that there is no - checksum in this packet. See + checksum in this packet. See for more information on the usage of this bit. Bit 7 is the Checksum Good bit and indicates that the checksum in - this packet has already been verified. See + this packet has already been verified. See for more information on the usage of this bit.
@@ -7489,7 +7839,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ (starting with the area at offset 0 for the first message received after the registration of the receive queue and looping back to the top after the last area is used) in the receive queue is written with a message - descriptor as shown in + descriptor as shown in . Either the entire entry is atomically written, or the write order is serialized such that the control field is globally visible after all other fields are @@ -7543,15 +7893,15 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ 0 if the buffer does not contain a valid message, in which case the device driver recycles the buffer. Bits 2-4 Reserved. - Bit 5: Large Send Indication bit. If a 1, then this + Bit 5: Large Send Indication bit. If a 1, then this indicates the packet is a large-send packet. Bit 6: No Checksum bit. If a 1, then this indicates that - there is no checksum in this packet (see + there is no checksum in this packet (see for more information on the usage of this bit). Bit 7: Checksum Good bit. If a 1, then this indicates that the checksum in this packet has already been verified (see - + for more information on the usage of this bit). @@ -7652,7 +8002,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ also toggled/read from the receive queue descriptor’s valid bit toggle bit, on each cycle through the circular buffer. After all valid receive queue entries are serviced, the device driver resets the - interrupt. + interrupt. . After the interrupt reset, the device driver again scans from the new value of the receive queue service pointer to pick up any entries that may have been enqueued during @@ -7810,8 +8160,8 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */
Logical LAN Device Tree Node - The Logical LAN device tree node is a child of the - vdevice node which itself is a child of + The Logical LAN device tree node is a child of the + vdevice node which itself is a child of / (the root node). There exists one such node for each logical LAN virtual IOA instance. Additionally, Logical LAN device tree nodes have associated packages such as obp-tftp and load method as @@ -7857,9 +8207,9 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name per + Standard property name per , specifying the - virtual device name, the value shall be + virtual device name, the value shall be “l-lan”. @@ -7873,9 +8223,9 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name per + Standard property name per , specifying the - virtual device type, the value shall be + virtual device type, the value shall be “network”. @@ -7902,10 +8252,10 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name per + Standard property name per , specifying the programming models that are compatible with this virtual IOA, - the value shall include + the value shall include “IBM,l-lan”. @@ -7934,7 +8284,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Property name specifying the unique and persistent location code associated with this virtual IOA, the value shall - be of the form defined in + be of the form defined in . @@ -7948,16 +8298,16 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name per + Standard property name per , specifying the unit address (unit ID) associated with this virtual IOA presented as - an encoded array as with - encode-phys of length + an encoded array as with + encode-phys of length “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -7973,9 +8323,9 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Property name specifying the DMA window associated with this virtual IOA presented as an encoded array of three values - (LIOBN, phys, size) encoded as with - encode-int, - encode-phys, and + (LIOBN, phys, size) encoded as with + encode-int, + encode-phys, and encode-int. @@ -7989,7 +8339,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name per + Standard property name per , specifying the locally administered MAC addresses are denoted by having the low order two bits of the high order byte being 0b10. @@ -8027,7 +8377,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Property name specifying the number of non-broadcast multicast MAC filters supported by this implementation (between - 0 and 255) presented as an encoded array encoded as with + 0 and 255) presented as an encoded array encoded as with encode-int. @@ -8043,7 +8393,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ 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 + 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 @@ -8104,7 +8454,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ This property is required when any of the ILLAN - sub-options are implemented (see + sub-options are implemented (see ). The existence of this property indicates that the H_ILLAN_ATTRIBUTES hcall() is implemented, and that hcall() is then used to determine which @@ -8121,8 +8471,8 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name as per - . + Standard property name as per + . Reports possible types of “network” the device can support. @@ -8137,8 +8487,8 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name as per - . + Standard property name as per + . Reports the type of “network” this device is supporting. @@ -8153,7 +8503,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name per + Standard property name per , to indicate maximum packet size. @@ -8168,7 +8518,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Y - Standard property name per + Standard property name per , to indicate network address length. @@ -8188,9 +8538,9 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ 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 + definition for the “ibm,#dma-size-cells” property - in + in . @@ -8209,8 +8559,8 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ 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 + definition for the + “ibm,#dma-address-cells” property in . @@ -8225,7 +8575,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Receive Queue to one of two modes using the H_VIO_SIGNAL hcall(). These are: - + Disabled (An enqueue interrupt is not signaled.) @@ -8234,7 +8584,7 @@ hcall ( const int64 H_SEND_SUB_CRQ, /* Function Code */ Enabled (An enqueue interrupt is signaled on every enqueue) - + Note: An enqueue is considered a pulse not a level. The pulse then sets the memory element within the emulated interrupt @@ -8273,82 +8623,82 @@ hcall ( const unit64 H_REGISTER_LOGICAL_LAN, /*Register structures for the logic Parameters: - + - unit-address: As specified in the Logical LAN device tree node + unit-address: As specified in the Logical LAN device tree node “reg” property - + buf-list: I/O address of a 4 KB page (aligned) used to record registered input buffers - + rec-queue: Buffer descriptor of a receive queue, specifying a receive queue which is a multiple of 16 bytes in length and is 16 byte aligned - + filter-list: I/O address of a 4 KB page aligned broadcast MAC address filter list - + mac-address: The receive filter MAC address - + Semantics: - + Validate the Unit Address else H_Parameter - + Validate the I/O addresses of the buf-list and filter-list is in the TCE and is 4K byte aligned else H_Parameter - + Validate the Buffer Descriptor of the receive queue buffer (I/O addresses for entire buffer length starting at the specified I/O address are translated by the RTCE table, length is a multiple of 16 bytes, and alignment is on a 16 byte boundary) else H_Parameter. - + Initialize the one page buffer list - + Enqueue the receive queue buffer (set valid toggle to 0). - + Initialize the hypervisor’s receive queue enqueue pointer and length variables for the virtual IOA associated with the Unit Address. These variables are kept in terms of DMA addresses so that page migration works and any remapping of TCEs is effective. - + Disable receive queue interrupts. - + Record the low order 6 bytes of mac-address for filtering future incoming messages. - + Return H_Success. - +
@@ -8371,37 +8721,37 @@ hcall ( const uint64 H_FREE_LOGICAL_LAN, /*Deregister structures for the logical Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property. - + Semantics: - + Validate the Unit Address else H_Parameter - + Interlock/carefully manipulate tables so that H_SEND_LOGICAL_LAN performs safely. - + Clear the associated page buffer list, prevent further consumption of receive buffers and generation of receive interrupts. - + Return H_Success. - + H_FREE_LOGICAL_LAN is the only valid mechanism to reclaim the memory pages registered via H_REGISTER_LOGICAL_LAN. @@ -8438,45 +8788,45 @@ hcall ( const uint64 H_ADD_LOGICAL_LAN_BUFFER,/* Adds a receive buffer to the */ Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property - + buf: Buffer Descriptor of new I/O buffer - + Semantics: - + Checks that unit address is OK else H_Parameter. - + Checks that I/O Address is within range of DMA window. - + Scans the buffer list for a pool of buffers of the length specified in the Descriptor - + If one does not exist (and there is still room in the buffer list, create a new pool entry else H_Resource). - + Uses enqueue procedure that is compatible with H_SEND_LOGICAL_LAN hcall()’s dequeue procedure - + Implementation Note: Since the buffer queue is based upon I/O addresses that are checked by H_SEND_LOGICAL_LAN, it is only necessary to @@ -8511,38 +8861,38 @@ hcall ( const uint64 H_FREE_LOGICAL_LAN_BUFFER,/* Removes a buffer of the specif Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property. - + bufsize: The size of the buffer that is being requested to be removed from the receive buffer pool. - + Semantics: - + Check that unit address is valid, else return H_Parameter. - + Scan the buffer list for a pool of buffers of the length specified in bufsize, and return H_Not_Found if one does not exist. - + Place an entry on receive queue for buffer of specified size, with Control field Bit 1 set to 0, and return H_Success - + @@ -8574,122 +8924,122 @@ hcall ( const uint64 H_SEND_LOGICAL_LAN, /* Send a message on the logical LAN */ Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property - + buff-1: Buffer Descriptor #1 - + buff-2: Buffer Descriptor #2 - + buff-3: Buffer Descriptor #3 - + buff-4: Buffer Descriptor #4 - + buff-5: Buffer Descriptor #5 - + buff-6: Buffer Descriptor #6 - + continue-token: Used to continue a transfer if H_Busy is returned. Set to 0 on the first call. If H_Busy is returned, then call again but use the value returned in R4 from the previous call as the value of continue-token. - + Semantics: - + If continue-token is non-zero, then do appropriate checks to see that parameters and buffers are still valid, and pickup where the previous transfer left off for the specified unit address, based on the value of the continue-token. - + If continue-token is zero and if previous H_SEND_LOGICAL_LAN for the specified unit address was suspended with H_Busy and never completed, then cleanup the state from the previously suspended call before proceeding. - + Verifies the VLAN number -- else H_Parameter. - + Proceeds down the 6 buffer descriptors until the first one that has a length of 0 - + - If the + If the “ibm,max-virtual-dma-size” property exist - in the + in the /vdevice node of the device tree, then if the length is greater than the value of this property, return H_Parameter - + For the length of the buffer: - + Verifies the I/O buffer addresses translate through the sender’s RTCE table else H_Parameter. - + - + - + Verifies the destination MAC address for the VLAN - + If MAC address is not cached and there exists a Trunk Adapter for the VLAN, then flags the message as destined for the Trunk Adapter and continues processing - + If MAC address is not cached and a Trunk Adapter does not exist for the VLAN, then drop the message (H_Dropped) - + - + For each Destination MAC Address (broadcast MAC address turns into multi-cast to all destinations on the specified VLAN): - + In the case of multicast MAC addresses the following algorithm defines the members of the receiver class for a given VLAN: For each logical lan IOA that would be a target for a broadcast from the source IOA: - + If the receiving IOA is not enabled for non-broadcast multicast frames then continue @@ -8700,7 +9050,7 @@ hcall ( const uint64 H_SEND_LOGICAL_LAN, /* Send a message on the logical LAN */ multicast frames then copy the frame to the IOA's receive buffer Else - + If (lookup filter (table index)) then copy the frame to the IOA's receive buffer @@ -8711,46 +9061,46 @@ hcall ( const uint64 H_SEND_LOGICAL_LAN, /* Send a message on the logical LAN */ non-broadcast multicast frames then copy the frame to the IOA's receive buffer /*allows for races on filter insertion */ - + - + int lookup filter (table index) - + Firmware implementation designed algorithm - + - + Searches the receiver’s receive queue for a suitable buffer and atomically dequeues it: - + If no suitable buffer is found, the receiver’s dropped packet counter (last 8 bytes of buffer list) is incremented and processing proceeds to the next receiver if any. - + - + Copy the send data in to the selected receive buffer, build a receive queue entry, and generate an interrupt to the receiver if the interrupt is enabled. - + - + If any frames were dropped return H_Dropped else return H_Success. - + Firmware Implementation Note: If during the processing of the H_SEND_LOGICAL_LAN call, it becomes necessary to @@ -8790,7 +9140,7 @@ hcall ( const uint64 H_SEND_LOGICAL_LAN, /* Send a message on the logical LAN */ firmware to filter multicast packets for it. That is, receive packets only if they contain multicast addresses specified by the device driver. The number of simultaneous multicast packet filters supported is - implementation dependent, and is specified in the + implementation dependent, and is specified in the “ibm,mac-address-filters” property of the l-lan device tree node. Therefore, the device driver must be prepared to have any filter request fail, and fall back to enabling reception of all @@ -8829,7 +9179,7 @@ hcall ( const uint64 H_MULTICAST_CTRL, /* Controls multicast address filtering. /* Bit 44 = 0 do not modify enable reception of */ /* multicast frames value of bit 46 ignored */ /* Bit 44 = 1 modify enable reception of multicast */ - /* frames + /* frames /* if bit 46 = 1 allow reception of multicast */ /* frames */ /* if bit 46 = 0 prohibit reception of all */ @@ -8862,22 +9212,22 @@ hcall ( const uint64 H_MULTICAST_CTRL, /* Controls multicast address filtering. Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property - + flags: Only bits 44-47 and 62-63 are defined all other bits should be zero. - + multi-cast-address: Multicast MAC address, if flag bits 62 and 63 are 01 or 10, else this parameter is ignored. - + Return value in register R4: State of Enables and Count of MAC Filters in table. @@ -8893,90 +9243,90 @@ hcall ( const uint64 H_MULTICAST_CTRL, /* Controls multicast address filtering. Semantics: - + Validate the unit-address parameter else return H_Parameter. - + Validate that no reserved flag bit = 1 else return H_Parameter. - + If any bits are on in the high order two bytes of the MAC parameter Return H_Parameter - + Modify Enables per specification if requested. - + Modify the Filter Table per specification if requested filtering is disable during any filter table modification and filter enable state restored after filter table modification). - + If don't modify RC=H_Success - + If Clear all: initialize the filter table, RC=H_Success - + If Add: - + If there is room in the table insert new MAC Filter entry, MAC Filter count++, RC=H_Success - + Else RC=H_Constrained - + (duplicates are silently dropped -- filter count stays the same RC=H_Success) - + - + If Remove: - + Locate the specified entry in the MAC Filter Table - + If Found remove the entry, MAC Filter count--, RC=H_Success - + Else RC=H_Not_Found - + - + - + Load the Enable Bits into R4 bits 46 and 47 Load the MAC Filter count into R4 Bits 48-63 - + Return RC - + @@ -8999,35 +9349,35 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ Parameters: - + - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property - + mac-address: The new receive filter MAC address - + Semantics: - + Validates the unit address, else H_Parameter - + Records the low order 6 bytes of mac-address for filtering future incoming messages - + Returns H_Success - + @@ -9035,8 +9385,8 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ H_ILLAN_ATTRIBUTES There are certain ILLAN attributes that are made visible to and can be manipulated by partition software. The H_ILLAN_ATTRIBUTES hcall is - used to read and modify the attributes (see - ). + used to read and modify the attributes (see + ). defines the attributes that are visible and manipulatable.   @@ -9121,7 +9471,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ This bit is implemented when the ILLAN Checksum Offload - Padded Packet Support option is implemented. See + Padded Packet Support option is implemented. See . 0: Software must not request checksum offload, by setting Bit 6 of the buffer descriptor (the No Checksum bit), for @@ -9145,7 +9495,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ incoming packets, when a reasonable size buffer is not available. The state of this bit cannot be changed between the time that the ILLAN is registered by an H_REGISTER_LOGICAL_LAN - and it is deregistered by an H_FREE_LOGICAL_LAN. See also + and it is deregistered by an H_FREE_LOGICAL_LAN. See also . 1: The hypervisor will keep a history of what buffer sizes have been registered. When a packets arrives the history @@ -9181,7 +9531,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ may not be changeable by the partition firmware via the H_ILLAN_ATTRIBUTES hcall() (platform implementation dependent). If not changeable, then attempts to change this field will - result in a return code of H_Constrained. See also + result in a return code of H_Constrained. See also . @@ -9222,7 +9572,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ a 1 in the set-mask). This state of this bit cannot be changed between the time that the ILLAN is registered by an H_REGISTER_LOGICAL_LAN and it is deregistered by an - H_FREE_LOGICAL_LAN. See + H_FREE_LOGICAL_LAN. See for more information. 1: The partition software has indicated that it supports @@ -9260,7 +9610,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ a 1 in the set-mask). This state of this bit cannot be changed between the time that the ILLAN is registered by an H_REGISTER_LOGICAL_LAN and it is deregistered by an - H_FREE_LOGICAL_LAN. See + H_FREE_LOGICAL_LAN. See for more information. 1: The partition software has indicated that it supports @@ -9301,7 +9651,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ This bit will be changed from a 1 to a 0 by the firmware when another Trunk Adapter has had its Active Trunk Adapter bit changed from a 0 to a 1. - See + See for more information. 1: The VIOA is the active Trunk Adapter. @@ -9315,20 +9665,20 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ - R1-R1--1. If the H_ILLAN_ATTRIBUTES hcall is - implemented, then it must implement the attributes as they are defined in + implemented, then it must implement the attributes as they are defined in and the syntax and semantics as - defined in + defined in . - + - R1-R1--2. @@ -9339,7 +9689,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ returned), and must return the following for the ILLAN Attributes in R4: - + A value of 0 for unimplemented bit positions. @@ -9347,7 +9697,7 @@ hcall ( const uint64 H_CHANGE_LOGICAL_LAN_MAC, /* Change the MAC address */ The resultant field values for implemented fields. - + @@ -9374,12 +9724,12 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Parameters: - unit-address: Unit Address per device tree node + unit-address: Unit Address per device tree node “reg” property. The ILLAN unit address on which this Attribute modification is to be performed. reset-mask: The bit-significant mask of bits to be reset in the ILLAN’s Attributes (the reset-mask bit definition aligns with the - bit definition of the ILLAN’s Attributes, as defined in + bit definition of the ILLAN’s Attributes, as defined in ). The complement of the reset-mask is ANDed with the ILLAN’s Attributes, prior to applying the set-mask. See semantics for more details on any field-specific @@ -9388,7 +9738,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ corresponding bit(s) in the reset-mask are ignored. set-mask: The bit-significant mask of bits to be set in the ILLAN’s Attributes (the set-mask bit definition aligns with the bit - definition of the ILLAN’s Attributes, as defined in + definition of the ILLAN’s Attributes, as defined in ). The set-mask is ORed with the ILLAN’s Attributes, after to applying the reset-mask. See semantics for more details on any field-specific actions needed during @@ -9400,129 +9750,129 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Semantics: - + Validate that Unit Address belongs to the partition, else H_Parameter. - + Reset/set the bits in the ILLAN Attributes, as indicated by the rest-mask and set-mask except as indicated in the following conditions. - + If the Buffer Size Control bit is trying to be changed from a 0 to a 1 and any of the following is true, then do not allow the change (H_Constrained will be returned): - + The ILLAN is active. That is, the ILLAN has been registered (H_REGISTER_LOGICAL_LAN) but has not be deregistered (H_FREE_LOGICAL_LAN). - + The firmware does not support the ILLAN Buffer Size Control option. - + - + If the Buffer Size Control bit is trying to be changed from a 1 to a 0 and any of the following is true, then do not allow the change (H_Constrained will be returned): - + The ILLAN is active. That is, the ILLAN has been registered (H_REGISTER_LOGICAL_LAN) but has not be deregistered (H_FREE_LOGICAL_LAN). - + - + If either the TCP Checksum Offload Support for IPv4 bit or TCP Checksum Offload Support for IPv6 bit is trying to be changed from a 0 to a 1 and any of the following is true, then do not allow the change (H_Constrained will be returned): - + The ILLAN is active. That is, the ILLAN has been registered (H_REGISTER_LOGICAL_LAN) but has not be deregistered (H_FREE_LOGICAL_LAN). - + The firmware does not support the ILLAN Checksum Offload Support option or supports it, but not for the specified protocol(s) or does not support it for this VIOA. - + - + If the TCP Checksum Offload Support for IPv4 bit or TCP Checksum Offload Support for IPv6 bit is trying to be changed from a 1 to a 0 and any of the following is true, then do not allow the change (H_Constrained will be returned): - + The ILLAN is active. That is, the ILLAN has been registered (H_REGISTER_LOGICAL_LAN) but has not be deregistered (H_FREE_LOGICAL_LAN). - + - + If the Active Trunk Adapter bit is trying to be changed from a 0 to a 1 and any of the following is true, then do not allow the change (H_Constrained will be returned): - + The firmware does not support the ILLAN Backup Trunk Adapter option or this VIOA is not a Trunk Adapter. - + - + If the Active Trunk Adapter bit is trying to be changed from a 1 to a 0, then return H_Parameter. - + If the Active Trunk Adapter bit is changed from a 0 to a 1 for a VIOA, then also set any previously active Trunk Adapter’s Active Trunk Adapter bit from a 1 to a 0. - + If the Trunk Adapter Priority field is trying to be changed from 0 to a non-0 value, then return H_Parameter. - + If the Trunk Adapter Priority field is trying to be changed from a non-0 value to another non-0 value and either the parameter is not changeable or the change is not within the platform allowed limits, then do not allow the change (H_Constrained will be returned). - + Load R4 with the value of the ILLAN’s Attributes, with any unimplemented bits set to 0, and if all requested changes were made then return H_Success, otherwise return H_Constrained. - + @@ -9574,9 +9924,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Option Platforms may combine the Logical LAN option with most other LoPAR options such as dynamic reconfiguration by including the appropriate OF - properties and extending the associated firmware calls. However, the + properties and extending the associated firmware calls. However, the ibm,set-xive, ibm,get-xive, ibm,int-off, - and + and ibm,int-on RTAS calls are extended as part of the base support. @@ -9588,26 +9938,26 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. For the ILLAN option: The platform must interpret - logical LAN buffer descriptors as defined in + logical LAN buffer descriptors as defined in . - + - R1-R1--2. For the ILLAN option: The platform must reject logical LAN buffer descriptors that are not 8 byte aligned. - + - R1-R1--3. For the ILLAN option: The platform must interpret the @@ -9615,9 +9965,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ order bit being the valid bit. - + - R1-R1--4. For the ILLAN option: The platform must set the next @@ -9626,63 +9976,63 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ being used to indicate a valid receive queue entry. - + - R1-R1--5. For the ILLAN option: The platform must interpret the 2nd through 4th bytes of a logical LAN buffer descriptor as the binary length of the buffer in I/O space (relative to the TCE mapping table - defined by the logical IOA’s + defined by the logical IOA’s “ibm,my-dma-window” property). - + - R1-R1--6. For the ILLAN option: The platform must interpret the 5th through 8th bytes of a logical LAN buffer descriptor as the binary beginning address of the buffer in I/O space (relative to the TCE mapping - table defined by the logical IOA’s + table defined by the logical IOA’s “ibm,my-dma-window” property). - + - R1-R1--7. For the ILLAN option: The platform must interpret - logical LAN Buffer Lists as defined in + logical LAN Buffer Lists as defined in . - + - R1-R1--8. For the ILLAN option: The platform must reject logical LAN Buffer Lists that are not mapped relative to the TCE mapping - table defined by the logical IOA’s + table defined by the logical IOA’s “ibm,my-dma-window” property. - + - R1-R1--9. For the ILLAN option: The platform must reject logical LAN buffer lists that are not 4 KB aligned. - + - R1-R1--10. For the ILLAN option: The platform must interpret the @@ -9690,30 +10040,30 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ logical IOA’s Receive Queue. - + - R1-R1--11. For the ILLAN option: The platform must interpret the - logical LAN receive queue as defined in + logical LAN receive queue as defined in . - + - R1-R1--12. For the ILLAN option: The platform must reject a logical LAN receive queue that is not mapped relative to the TCE mapping - table defined by the logical IOA’s + table defined by the logical IOA’s “ibm,my-dma-window” property. - + - R1-R1--13. For the ILLAN option: The platform must reject a @@ -9721,9 +10071,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ boundary. - + - R1-R1--14. For the ILLAN option: The platform must reject a @@ -9731,18 +10081,18 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ long. - + - R1-R1--15. For the ILLAN option: The platform must manage the logical LAN receive queue as a circular buffer. - + - R1-R1--16. For the ILLAN option: The platform must enqueue 12 @@ -9750,9 +10100,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ received. - + - R1-R1--17. For the ILLAN option: @@ -9763,9 +10113,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ bytes of the logical LAN receive queue entry. - + - R1-R1--18. For the ILLAN option: @@ -9775,13 +10125,13 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ the valid toggle in the receive queue buffer descriptor, next bit to a one if the message payload is valid) and the last 3 bytes contains the receive message length, after setting the correlator field in the last 8 - bytes per Requirement + bytes per Requirement . - + - R1-R1--19. For the ILLAN option: The platform must when crossing @@ -9790,9 +10140,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ descriptor. - + - R1-R1--20. For the ILLAN option: The platform’s OF must @@ -9800,9 +10150,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ control to the booted client program. - + - R1-R1--21. For the ILLAN option: The platform must present (as @@ -9815,9 +10165,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ the interrupt source number is still outstanding. - + - R1-R1--22. For the ILLAN option: The platform must NOT present @@ -9828,30 +10178,30 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ interrupt from the interrupt source number is still outstanding. - + - R1-R1--23. For the ILLAN option: The platform must interpret - logical LAN receive buffers as defined in + logical LAN receive buffers as defined in . - + - R1-R1--24. For the ILLAN option: The platform must reject a logical LAN receive buffer that is not mapped relative to the TCE mapping - table defined by the logical IOA’s + table defined by the logical IOA’s “ibm,my-dma-window” property. - + - R1-R1--25. For the ILLAN option: The platform must reject a @@ -9859,18 +10209,18 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ boundary. - + - R1-R1--26. For the ILLAN option: The platform must reject a logical LAN receive buffer that is not a minimum of 16 bytes long. - + - R1-R1--27. For the ILLAN option: The platform must not modify @@ -9878,9 +10228,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ for a user supplied correlator value. - + - R1-R1--28. For the ILLAN option: The platform must not allow @@ -9889,61 +10239,61 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ partition I/O operation). - + - R1-R1--29. - For the ILLAN option: The platform’s + For the ILLAN option: The platform’s l-lan OF device tree node must contain properties as - defined in + defined in . (Other standard I/O adapter properties are permissible as appropriate.) - + - R1-R1--30. For the ILLAN option: The platform must implement the - H_REGISTER_LOGICAL_LAN hcall() as defined in + H_REGISTER_LOGICAL_LAN hcall() as defined in . - + - R1-R1--31. For the ILLAN option: The platform must implement the - H_FREE_LOGICAL_LAN hcall() as defined in + H_FREE_LOGICAL_LAN hcall() as defined in . - + - R1-R1--32. For the ILLAN option: The platform must implement the - H_ADD_LOGICAL_LAN_BUFFER hcall() as defined in + H_ADD_LOGICAL_LAN_BUFFER hcall() as defined in . - + - R1-R1--33. For the ILLAN option: The platform must implement the - H_SEND_LOGICAL_LAN hcall() as defined in + H_SEND_LOGICAL_LAN hcall() as defined in . - + - R1-R1--34. For the ILLAN option: The platform must implement the @@ -9953,77 +10303,77 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ operations.) - + - R1-R1--35. For the ILLAN option: The platform must implement the - H_CHANGE_LOGICAL_LAN_MAC hcall() as defined in + H_CHANGE_LOGICAL_LAN_MAC hcall() as defined in . - + - R1-R1--36. For the ILLAN option: The platform must implement the - H_VIO_SIGNAL hcall() as defined in + H_VIO_SIGNAL hcall() as defined in . - + - R1-R1--37. For the ILLAN option: The platform must implement the - extensions to the H_EOI hcall() as defined in + extensions to the H_EOI hcall() as defined in . - + - R1-R1--38. For the ILLAN option: The platform must implement the - extensions to the H_XIRR hcall() as defined in + extensions to the H_XIRR hcall() as defined in . - + - R1-R1--39. For the ILLAN option: The platform must implement the H_PUT_TCE hcall(). - + - R1-R1--40. For the ILLAN option: The platform must implement the H_GET_TCE hcall(). - + - R1-R1--41. For the ILLAN option: The platform must implement the - extensions to the H_MIGRATE_DMA hcall() as defined in + extensions to the H_MIGRATE_DMA hcall() as defined in . - + - R1-R1--42. For the ILLAN option: The platforms must emulate the @@ -10044,7 +10394,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ be ascertained by the H_ILLAN_ATTRIBUTES hcall(). The same hcall() may be used by the partition software to communicate back to the firmware the level of support for those options where the firmware needs to know the - level of partition software support. The + level of partition software support. The “ibm,illan-options” property will exist in the VIOA’s Device Tree node, indicating that the H_ILLAN_ATTRIBUTES hcall() is implemented, and therefore that one or more @@ -10056,7 +10406,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ The ILLAN Backup Trunk Adapter option allows the platform to provide one or more backups to a Trunk Adapter, for reliability purposes. Implementation of the ILLAN Backup Trunk Adapter option is specified to - the partition by the existence of the + the partition by the existence of the “ibm,illan-options” property in the VIOA’s Device Tree node and a non-0 value in the ILLAN Attributes Backup Trunk adapter Priority field. A Trunk Adapter becomes the active @@ -10067,56 +10417,56 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. For the ILLAN Backup Trunk Adapter option: The platform must implement the ILLAN option. - + - R1-R1--2. For the ILLAN Backup Trunk Adapter option: The platform must implement the H_ILLAN_ATTRIBUTES hcall(). - + - R1-R1--3. For the ILLAN Backup Trunk Adapter option: The - platform must implement the - “ibm,illan-options” and + platform must implement the + “ibm,illan-options” and “ibm,trunk-adapter” properties in all the Trunk Adapter nodes of the Device Tree. - + - R1-R1--4. For the ILLAN Backup Trunk Adapter option: The platform must implement the Active Trunk Adapter bit and the Backup Trunk - Adapter Priority field in the ILLAN Attributes, as defined in + Adapter Priority field in the ILLAN Attributes, as defined in , for all Trunk Adapter VIOAs. - + - R1-R1--5. For the ILLAN Backup Trunk Adapter option: The platform must allow only one Trunk Adapter to be active for a VLAN at any given time, and must: - + Make the determination of which one is active by whichever was the most recent one to set its Active Trunk Adapter bit in their ILLAN @@ -10128,7 +10478,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ for a Trunk Adapter when it is removed from the active Trunk Adapter state. - + @@ -10147,7 +10497,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ The H_ILLAN_ATTRIUBTES hcall is used to establish the common set of checksum offload protocols to be supported between the firmware and the partition software. The firmware indicates support for H_ILLAN_ATTRIBUTES - via the + via the “ibm,illan-options” property in the VIOA’s Device Tree node. The partition software can determine which of the Checksum Offload protocols (if any) that the firmware supports by @@ -10158,23 +10508,23 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ partition and the firmware). Two bits in the control field of the first buffer descriptor specify which operations do not contain a checksum and which have had - their checksum already verified. See + their checksum already verified. See . These two bits get transferred to the corresponding control field of the Receive Queue Entry, with the exception that the H_SEND_LOGICAL_LAN hcall will - sometimes set these to 0b00 (see + sometimes set these to 0b00 (see ). - R1-R1--1. For the ILLAN Checksum Offload Support option: The platform must do all the following: - + Implement the ILLAN option. @@ -10184,17 +10534,17 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - Implement the + Implement the “ibm,illan-options” property in the VIOA’s Device Tree node. Implement the appropriate Checksum Offload Support bit(s) of the - ILLAN Attributes, as defined in + ILLAN Attributes, as defined in . - + Software Implementation Note: Fragmentation and encryption are not supported when the No Checksum bit of the Buffer @@ -10207,21 +10557,21 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
H_SEND_LOGICAL_LAN Semantic Changes There are several H_SEND_LOGICAL_LAN semantic changes required for - the ILLAN Checksum Offload Support option. See + the ILLAN Checksum Offload Support option. See for the base semantics. - R1-R1--1. For the ILLAN Checksum Offload Support option: The H_SEND_LOGICAL_LAN semantics must be changed as follows: - + - As shown in + As shown in , and for multi-cast operations, the determination in this table must be applied for each destination. @@ -10233,7 +10583,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ address does not match the adapter's MAC address, then drop the packet. - +  
@@ -10474,20 +10824,20 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
- + - R1-R1--2. For the ILLAN Checksum Offload Support option: The - Receiver DD Additional Requirements shown in + Receiver DD Additional Requirements shown in must be implemented. - + - R1-R1--3. @@ -10510,25 +10860,25 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. For the Checksum Offload Padded Packet Support Option: The platform must do all the following: - + Implement the ILLAN Checksum Offload Support option. Implement the Checksum Offload Padded Support bit of the ILLAN - Attributes, as defined in + Attributes, as defined in , and set that bit to a value of 1. - + @@ -10554,19 +10904,19 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
General The following are the general requirements for this option. For - H_SEND_LOGICAL_LAN changes, see + H_SEND_LOGICAL_LAN changes, see . - R1-R1--1. For the ILLAN Buffer Size Control option: The platform must do all the following: - + Implement the ILLAN option. @@ -10576,17 +10926,17 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - Implement the + Implement the “ibm,illan-options” property in the VIOA’s Device Tree node. Implement the Buffer Size Control bit of the ILLAN Attributes, - as defined in + as defined in . - + @@ -10600,7 +10950,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. @@ -10617,36 +10967,36 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
- +
ILLAN Large Send Indication option - - This option allows the virtual device to send an + + This option allows the virtual device to send an indication to the receiver that the data being sent by H_SEND_LOGICAL_LAN contains a large send packet. - +
General - + The following are the general requirements for this option. For H_SEND_LOGICAL_LAN changes, see . - + - R1-R1--1. - + - For the ILLAN Large send indication option: + For the ILLAN Large send indication option: The platform must do all the following: - + Implement the H_ILLAN_ATTRIBUTES hcall(). - + - Implement the Large Send Indication bit of the ILLAN Attributes as defined in + Implement the Large Send Indication bit of the ILLAN Attributes as defined in . @@ -10655,21 +11005,21 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
- +
H_SEND_LOGICAL_LAN Semantic Changes - + The following are the required semantic changes to the H_SEND_LOGICAL_LAN hcall(). - R1-R1--1. - For the ILLAN Large send indication option: - When the Large Send Indication bit of the first buffer descriptor is set to 1, - then the firmware for the H_SEND_LOGICAL_LAN hcall() must set the Large Send Indication + For the ILLAN Large send indication option: + When the Large Send Indication bit of the first buffer descriptor is set to 1, + then the firmware for the H_SEND_LOGICAL_LAN hcall() must set the Large Send Indication bit in the receiver's receive queue entry to 1 when the packet is copied to the destination receive buffer. @@ -10687,7 +11037,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Transport and Logical Remote DMA of the Synchronous VIO Infrastructure to service I/O requests for code running in a client partition, such that, the client partition appears to enjoy the services of its own SCSI adapter (see - + ). The terms server and client partitions refer to platform partitions that are respectively servers and clients of requests, usually I/O operations, using the physical I/O @@ -10698,19 +11048,19 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ The VSCSI architecture is built upon the architecture specified in the following sections: - + - + - + - +
VSCSI General @@ -10738,13 +11088,13 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ OS builds its “physical to logical” configuration. The client partition’s device tree contains one or more nodes notifying the partition that it has been assigned one or more virtual - adapters. The node’s - “type” and + adapters. The node’s + “type” and “compatible” properties notify the - partition that the virtual adapter is a VSCSI adapter. The + partition that the virtual adapter is a VSCSI adapter. The unit address of the node is used by the client partition to map the virtual device(s) to the OS’s corresponding - logical representations. The + logical representations. The “ibm,my-dma-window” property communicates the size of the RTCE table window panes that the hypervisor has allocated. The node also specifies the interrupt source number that has @@ -10772,11 +11122,11 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ the client requests. The client partition, upon noting the device tree entry for the virtual adapter, loads the device driver associated with the value of the - + “compatible” property. The device driver, when configured and opened, allocates memory for its CRQ (an array, large enough for all possible responses, of 16 byte elements), pins the queue - and maps it into the I/O space of the RTCE window specified in the + and maps it into the I/O space of the RTCE window specified in the “ibm,my-dma-window” property using the standard kernel mapping services that subsequently use the H_PUT_TCE hcall(). The queue is then registered using the H_REG_CRQ hcall(). Next, @@ -10826,13 +11176,13 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ to use Logical Remote DMA for the virtual devices that is serving. The server partition, upon noting the device tree entry for the virtual adapter, loads the device driver associated with the value of the - + “compatible” property. 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 + 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(). Next, I/O request control blocks (within which the I/O request commands are built) are allocated, @@ -10860,7 +11210,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ the request queue element to transfer the SCSI request from the client partition’s I/O request control block to its own (allocated above), using the H_COPY_RDMA hcall() through the second window pane specified in - the + the “ibm,my-dma-window” property. The server partition’s device driver then uses kernel services, that are extended, to register the I/O request’s DMA descriptors into @@ -10880,7 +11230,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ recycles the resources recorded in the I/O request control block, and the block itself. The LIOBN value in the second window pane of the server - partition’s + partition’s “ibm,my-dma-window” property is intended to be an indirect reference to the RTCE table of the client partition. If, for some reason, the physical location of the client @@ -10953,9 +11303,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Format/Transport Event Code - For Valid Command Response Entries, see + For Valid Command Response Entries, see . For Transport Event - Codes see + Codes see . @@ -11207,7 +11557,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - See also + See also .
@@ -11218,31 +11568,31 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. For the VSCSI option: The platform must implement the - Reliable Command/Response Transport option as defined in + Reliable Command/Response Transport option as defined in . - + - R1-R1--2. For the VSCSI option: The platform must implement the - Logical Remote DMA option as defined in + 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 IOA’s that it has been assigned so that it can load and configure the correct device driver code. This information is provided by the OF device tree node associated - with the virtual IOA (see - and + with the virtual IOA (see + and ). @@ -11258,25 +11608,25 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. For the VSCSI option: The platform’s OF device - tree for client partitions must include as a child of the + tree for client partitions must include as a child of the /vdevice node, a node of name “v-scsi” as the parent of a sub-tree representing the virtual IOAs assigned to the partition. - + - R1-R1--2. - For the VSCSI option: The platform’s - v-scsi OF node must contain properties as defined in + For the VSCSI option: The platform’s + v-scsi OF node must contain properties as defined in (other standard I/O adapter properties are permissible as appropriate).   @@ -11317,10 +11667,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device name, the - value shall be + value shall be “v-scsi”. @@ -11334,11 +11684,11 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device type, the value shall be - + “vscsi”. @@ -11365,12 +11715,12 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the programming models that are - compatible with this virtual IOA, the value shall include - “IBM,v-scsi”. - “IBM,v-scsi-2” precedes + compatible with this virtual IOA, the value shall include + “IBM,v-scsi”. + “IBM,v-scsi-2” precedes “IBM,vsci” if it is included in the value of this property. @@ -11400,9 +11750,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Property name specifying the unique and persistent location code associated with this virtual IOA presented as an - encoded array as with + encoded array as with encode-string. The value shall be of the - form specified in + form specified in . @@ -11416,17 +11766,17 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , 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 + presented as an encoded array as with + encode-phys of length “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -11442,9 +11792,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Property name specifying the DMA window associated with this virtual IOA presented as an encoded array of three values - (LIOBN, phys, size) encoded as with - encode-int, - encode-phys, and + (LIOBN, phys, size) encoded as with + encode-int, + encode-phys, and encode-int. @@ -11460,7 +11810,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + 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 @@ -11497,9 +11847,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + definition for the “ibm,#dma-size-cells” property - in + in . @@ -11518,8 +11868,8 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + definition for the + “ibm,#dma-address-cells” property in . @@ -11528,15 +11878,15 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - + - R1-R1--3. - For the VSCSI option: The platform’s + For the VSCSI option: The platform’s v-scsi node must have as children the appropriate - block (disk) and byte + block (disk) and byte (tape) nodes. @@ -11549,26 +11899,26 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. For the VSCSI option: The platform’s OF device - tree for server partitions must include as a child of the - /vdevice node, a node of name + tree for server partitions must include as a child of the + /vdevice node, a node of name “v-scsi-host” as the parent of a sub-tree representing the virtual IOAs assigned to the partition. - + - R1-R1--2. - For the VSCSI option: The platform’s + For the VSCSI option: The platform’s v-scsi-host node must contain properties as defined - in + in (other standard I/O adapter properties are permissible as appropriate). @@ -11612,10 +11962,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device name, the - value shall be + value shall be “v-scsi-host”. @@ -11629,10 +11979,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device type, the - value shall be + value shall be “v-scsi-host”. @@ -11659,12 +12009,12 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the programming models that are - compatible with this virtual IOA, the value shall include - “IBM,v-scsi-host”. - “IBM,v-scsi-host-2” precedes + compatible with this virtual IOA, the value shall include + “IBM,v-scsi-host”. + “IBM,v-scsi-host-2” precedes “IBM,vsci-host” if it is included in the value of this property. @@ -11695,9 +12045,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Property name specifying the unique and persistent location code associated with this virtual IOA presented as an - encoded array as with + encoded array as with encode-string. The value shall be of the - form + form . @@ -11711,17 +12061,17 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , 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 + presented as an encoded array as with + encode-phys of length “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -11738,7 +12088,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + with encode-int, encode-phys, and encode-int. Of these two triples, the @@ -11746,10 +12096,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ memory, the second is the window pane through which the client partition maps its memory that it makes available to the server partition. (Note the mapping between the LIOBN in the second - window pane of a server virtual IOA’s + window pane of a server virtual IOA’s “ibm,my-dma-window” property and the corresponding client IOA’s RTCE table is made - when the CRQ successfully completes registration. See + when the CRQ successfully completes registration. See for more information on window panes.) @@ -11766,7 +12116,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + 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 @@ -11817,9 +12167,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + definition for the “ibm,#dma-size-cells” property - in + in . @@ -11838,8 +12188,8 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + definition for the + “ibm,#dma-address-cells” property in . @@ -11855,7 +12205,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Virtual Terminal (Vterm) This section defines the Virtual Terminal (Vterm) options (Client Vterm option and Server Vterm option). Vterm IOAs are of the hypervisor - simulated class of VIO. See also + simulated class of VIO. See also .
@@ -11869,33 +12219,33 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ A partition’s device tree contains one or more nodes notifying the partition that it has been assigned one or more Vterm client adapters (each LoPAR partition has at least one). The - node’s - “type” and + node’s + “type” and “compatible” properties notify the - partition that the virtual adapter is a Vterm client adapter. The + partition that the virtual adapter is a Vterm client adapter. The unit address of the node is used by the partition to map the virtual device(s) to the OS’s corresponding logical - representations. The node’s + representations. The node’s “interrupts” property, if it exists, specifies the interrupt source number that has been assigned to the client Vterm IOA for receive data. The partition, uses the H_GET_TERM_CHAR and H_PUT_TERM_CHAR hcall()s to receive data from and - send data to the client Vterm IOA. If the node contains the + send data to the client Vterm IOA. If the node contains the “interrupts” property, the partition may - optionally use the - ibm,int-on, - ibm,int-off, + optionally use the + ibm,int-on, + ibm,int-off, ibm,set-xive, ibm,get-xive RTAS calls, and the H_VIO_SIGNAL hcall() to manage the client Vterm IOA interrupt. A partition’s device tree may also contain one or more node(s) notifying the partition that it is requested to supply server - Vterm IOA services for one or more client Vterm IOAs. The node’s - “type” and + Vterm IOA services for one or more client Vterm IOAs. The node’s + “type” and “compatible” properties notify the partition that the virtual adapter is a server Vterm IOA. The unit address (Unit ID) of the node is used by the partition to map the virtual device(s) to the OS’s corresponding logical - representations. The node’s + representations. The node’s “interrupts” property specifies the interrupt source number that has been assigned to the server Vterm IOA for receive data. The partition uses the H_VTERM_PARTNER_INFO hcall() to @@ -11905,9 +12255,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ connection between a server and a client Vterm IOAs, and uses the H_GET_TERM_CHAR and H_PUT_TERM_CHAR hcall()s to receive data from and send data to the server Vterm IOA. In addition, the partition may - optionally use the - ibm,int-on, - ibm,int-off, + optionally use the + ibm,int-on, + ibm,int-off, ibm,set-xive, ibm,get-xive RTAS calls, and the H_VIO_SIGNAL hcall() to manage the server Vterm IOA interrupt. @@ -11966,15 +12316,15 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - The - “reg” property or the + The + “reg” property or the vty node(s) enumerates the valid client Vterm IOA unit address(es) - The - “reg” property or the + The + “reg” property or the vty-server node(s) enumerates the valid server Vterm IOA unit address(es) H_VTERM_PARTNER_INFO is used to getvalid client Vterm IOA partition ID(s) and corresponding @@ -12010,7 +12360,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. @@ -12038,7 +12388,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Parameters: - + termno: The unit address of the Vterm IOA, from the @@ -12049,7 +12399,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Semantics: - + Hypervisor checks the termno parameter for validity against the @@ -12080,7 +12430,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 @@ -12092,7 +12442,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 @@ -12110,89 +12460,89 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Syntax: - Parameters: - - + + - termno: The unit address of the Vterm IOA, from the + termno: The unit address of the Vterm IOA, from the “reg” property of the Vterm IOA. - + 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 R6 and proceeds toward the low order byte in register R7 - + Semantics: - + Hypervisor checks the termno parameter for validity against the Vterm IOA unit addresses assigned to the partition, else return H_Parameter. - + Hypervisor returns H_Hardware if it detects that the virtual console terminal physical connection is not working. - + Hypervisor returns H_Closed if it detects that the virtual console session is not open (in the case of connection to a server Vterm IOA, this means that the server code has not made the connection to this specific client Vterm IOA). - + 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. + 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. - +
Interrupts - The interrupt source number is presented in the - “interrupts” property of the + The interrupt source number is presented in the + “interrupts” property of the Vterm node, when receive queue interrupts are - implemented for the Vterm. The - ibm,int-on, - ibm,int-off, + implemented for the Vterm. The + ibm,int-on, + ibm,int-off, ibm,set-xive, ibm,get-xive RTAS calls, and H_VIO_SIGNAL hcall() are used to manage the interrupt. - Interrupts and the + Interrupts and the “interrupts” property are always implemented for the server Vterm IOA, and may be implemented for the client Vterm IOA. @@ -12211,21 +12561,21 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. For the Server Vterm option: The platform must - implement the - “interrupts” property in all server + implement the + “interrupts” property in all server Vterm device tree nodes ( vty-server), and must set the interrupt in that property for the receive data interrupt for the IOA. - + - R1-R1--2. @@ -12233,7 +12583,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ implemented, the characteristics of the Vterm interrupts must be as follows: - + All must be edge-triggered. @@ -12247,7 +12597,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ The receive interrupt must be activated when the Vterm connection from the client to the server goes from open to closed. - + @@ -12260,7 +12610,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. @@ -12268,31 +12618,31 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ H_TERM_CHAR hcall()s must be implemented. - + - R1-R1--2. For the Client Vterm option: The platform’s OF - device tree must include as a child of the + device tree must include as a child of the /vdevice node, one or more nodes of type “vty”; one for each client Vterm IOA. - + - R1-R1--3. - For the Client Vterm option: The platform’s - vty OF node must contain properties as defined in + For the Client Vterm option: The platform’s + vty OF node must contain properties as defined in (other standard I/O adapter properties are permissible as appropriate).   - Properties of the + <title>Properties of the <emphasis role="bold"><literal>vty</literal></emphasis> Node (Client Vterm IOA) @@ -12328,10 +12678,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device name. The - value shall be + value shall be “vty”. @@ -12345,10 +12695,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device type. The - value shall be + value shall be “serial”. @@ -12375,13 +12725,13 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the programming models that are - compatible with this virtual IOA. The value shall include + compatible with this virtual IOA. The value shall include “hvterm1” when the virtual IOA will connect to a server with no special protocol, and shall - include + include “hvterm-protocol” when the virtual IOA will connect to a server that requires a protocol to control modems or hardware control signals. @@ -12412,9 +12762,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Property name specifying the unique and persistent location code associated with this virtual IOA presented as an - encoded array as with + encoded array as with encode-string. The value shall be of the - form specified in + form specified in . @@ -12428,17 +12778,17 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , 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 + presented as an encoded array as with + encode-phys of length “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -12454,7 +12804,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + 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 @@ -12482,17 +12832,17 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */
- + - R1-R1--4. For the Client Vterm option: If the compatible - property in the - vty node is + property in the + vty node is “hvterm-protocol”, then the protocol - that the client must use is defined in the document entitled + that the client must use is defined in the document entitled Protocol for Support of Physical Serial Port Using a Virtual TTY Interface. @@ -12511,7 +12861,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - R1-R1--1. @@ -12520,29 +12870,29 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ hcall()s must be implemented. - + - R1-R1--2. For the Server Vterm option: The platform’s OF device tree for partitions implementing server Vterm IOAs must include as - a child of the - /vdevice node, one or more nodes of type + a child of the + /vdevice node, one or more nodes of type “vty-server”; one for each server Vterm IOA. - + - R1-R1--3. - For the Server Vterm option: The platform’s + For the Server Vterm option: The platform’s vty-server node must contain properties as defined in - + (other standard I/O adapter properties are permissible as appropriate). @@ -12550,7 +12900,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ - Properties of the + <title>Properties of the <emphasis role="bold"><literal>vty-server</literal></emphasis> Node (Server Vterm IOA) @@ -12586,10 +12936,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device name. The - value shall be + value shall be “vty-server”. @@ -12603,10 +12953,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the virtual device type. The - value shall be + value shall be “serial-server”. @@ -12633,10 +12983,10 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , specifying the programming models that are - compatible with this virtual IOA. The value shall include + compatible with this virtual IOA. The value shall include “hvterm2”. @@ -12665,9 +13015,9 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Property name specifying the unique and persistent location code associated with this virtual IOA presented as an - encoded array as with + encoded array as with encode-string. The value shall be of the - form + form . @@ -12681,17 +13031,17 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ Y - Standard property name per + Standard property name per , 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 specified by + presented as an encoded array as with + encode-phys of length specified by “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -12707,7 +13057,7 @@ hcall ( const uint64 H_ILLAN_ATTRIBUTES,/* Returns in R4 the resulting ILLAN */ 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 + 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 @@ -12785,26 +13135,26 @@ hcall ( const uint64 H_VTERM_PARTNER_INFO, /* Gets possible partner connections Parameters: - + unit-address: Virtual IOA’s unit address, as specified in the IOA’s device tree node. - + partner-partition-id: The partner partition ID of the last partner partition ID and partner unit address pair returned. If a value of 0xFF...FF is specified, the call returns the first item in the list. - + partner-unit-addr: The partner unit address of the last partner partition ID and partner unit address pair returned. If a value of 0xFF...FF is specified, the call returns the first item in the list. - + buffr-addr: The logical address of a single page in memory, belonging to the calling partition, which is used to return the next @@ -12813,14 +13163,14 @@ hcall ( const uint64 H_VTERM_PARTNER_INFO, /* Gets possible partner connections during the duration of the call, otherwise the call will fail. Buffer format on return with H_Success: - + First eight bytes: Eight byte partner partition ID of the partner partition ID and partner unit address pair from the list, or 0xFF...FF if partner partition ID and partner unit address passed in the input parameters was the last item in the list of valid connections. - + Second eight bytes: Eight byte partner unit address associated with the partner partition ID (as returned in first 8 bytes of the @@ -12828,7 +13178,7 @@ hcall ( const uint64 H_VTERM_PARTNER_INFO, /* Gets possible partner connections address passed in the input parameters was the last item in the list of valid connections. - + Beginning at the 17 byte in the buffer: NULL-terminated Converged Location Code associated with the partner unit address and partner @@ -12837,47 +13187,47 @@ hcall ( const uint64 H_VTERM_PARTNER_INFO, /* Gets possible partner connections in the input parameters was the last item in the list of valid connections. - + Semantics: - + Validate that unit-address belongs to the partition and to a server Vterm IOA, else H_Parameter. - + If partner-partition-id and partner-unit-addr together do not match a valid partner partition ID and partner unit address pair in the list of valid connections for this unit-address, then return H_Parameter. - + If the 4 KB page associated with buffr-addr does not belong to the calling partition, then return H_Parameter. - + If the buffer associated with buffr-addr does not begin on a 4 K boundary, then return H_Parameter. - + If the calling partition attempts to migrate the buffer page associated with buffr-addr during the duration of the H_VTERM_PARTNER_INFO call, then return H_Parameter. - + If partner-partition-id is equal to 0xFF...FF, then select the first item from the list of valid connections, format the buffer as specified, above, for this item, and return H_Success. - + If partner-partition-id and partner-unit-addr together matches a valid partner partition ID and partner unit address pair in the list of @@ -12886,7 +13236,7 @@ hcall ( const uint64 H_VTERM_PARTNER_INFO, /* Gets possible partner connections and partner unit address both set to 0xFF...FF, and the Converged Location Code set to the NULL string, and return H_Success. - + If partner-partition-id and partner-unit-addr together matches a valid partner partition ID and partner unit address pair in the list of @@ -12894,7 +13244,7 @@ hcall ( const uint64 H_VTERM_PARTNER_INFO, /* Gets possible partner connections connections, and format the buffer as specified, above, and return H_Success. - + @@ -12926,44 +13276,44 @@ hcall ( const uint64 H_REGISTER_VTERM, /* Makes connection between server and */ );]]> - + Parameters: - + unit-address: The server Virtual IOA’s unit address, as specified in the IOA’s device tree node. - + partner-partition-id: The partition ID of the partition ID and unit address pair to which to be connected. - + partner-unit-addr: The unit address of the partition ID and unit address pair to which to be connected. - + Semantics: - + Validate that unit-address belongs to the partition and to a server Vterm IOA and that there does not exist a valid connection between this server Vterm IOA and a partner, else H_Parameter. - + If partner-partition-id and partner-unit-addr together do not match a valid partition ID and unit address pair in the list of valid connections for this unit-address, then return H_Parameter, - - + + Else make connection between the server Vterm IOA specified by unit-address and the client Vterm IOA specified by the @@ -12971,10 +13321,10 @@ hcall ( const uint64 H_REGISTER_VTERM, /* Makes connection between server and */ H_PUT_TERM_CHAR and H_GET_TERM_CHAR operations to flow between the two Vterm IOAs, and return H_Success. - + - + Software Implementation Note: An H_Parameter will be returned to the H_REGISTER_VTERM if a DLPAR operation has been performed @@ -13016,24 +13366,24 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Parameters: - + unit-address: Virtual IOA’s unit address, as specified in the IOA’s device tree node. - + Semantics: - + Validate that the unit address belongs to the partition and to a server Vterm IOA and that there exists a valid connection between this server Vterm IOA and a partner, else H_Parameter. - + Break the connection between the server Vterm IOA specified by the unit address and the client Vterm IOA, preventing further @@ -13041,7 +13391,7 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne (until a future successful H_REGISTER_VTERM operation), and return H_Success. - + Implementation Note: If the hypervisor returns an H_Busy, H_LongBusyOrder1mSec, or H_LongBusyOrder10mSec, software must call H_FREE_VTERM again with the same parameters. Software may choose to @@ -13060,18 +13410,18 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne
Virtual Management Channel (VMC) - - PAPR Virtual Management Channel (VMC) support is provided + + 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 + 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 + to service and to send requests to platform code. The purpose of this interface is to communicate platform - management information between designated logical + management information between designated logical partition and the platform. - + The VMC architecture is built upon the architecture specified in the following sections: - + @@ -13083,70 +13433,70 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - +
Virtual Management Channel Requirements - + This normative section provides the general requirements for the support of VMC. - + - R1-R1--1. - For the VMC option:The platform must + For the VMC option:The platform must implement the Reliable Command/Response Transport option as defined in . - + - R1-R1--2. - For the VMC option:The platform must + 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 + 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 + 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 + 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-R1--1. - For the VMC option: The platform’s + 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 + 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-R1--2. - For the VMC option: The platform’s + For the VMC option: The platform’s vmc - Open Firmware node must contain properties as defined in + Open Firmware node must contain properties as defined in (other standard I/O adapter properties are permissible as appropriate). @@ -13187,8 +13537,8 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y - Standard property name per IEEE 1275 specifying the virtual - device name, the value shall be + Standard property name per IEEE 1275 specifying the virtual + device name, the value shall be “ibm,vmc”. @@ -13200,8 +13550,8 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y - Standard property name per IEEE 1275 specifying the virtual - device type, the value shall be + Standard property name per IEEE 1275 specifying the virtual + device type, the value shall be “ibm,vmc”. @@ -13224,8 +13574,8 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y - Standard property name per IEEE 1275 specifying the programming - models that are compatible with this virtual IOA, the value shall be + Standard property name per IEEE 1275 specifying the programming + models that are compatible with this virtual IOA, the value shall be “IBM,vmc”. @@ -13248,12 +13598,12 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y - Property name specifying the unique and + Property name specifying the unique and persistent location code associated with this virtual IOA - presented as an encoded array as with - encode-string. + presented as an encoded array as with + encode-string. The value shall be of the form specified in - information on + information on Virtual Card Connector Location Codes. @@ -13265,15 +13615,15 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y - Standard property name per IEEE 1275 specifying the + Standard property name per IEEE 1275 specifying the register addresses, used as the unit address (unit - ID), associated with this virtual IOA presented as + 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 + “#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). @@ -13285,16 +13635,16 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y - Property name specifying the DMA window + 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. + encode-int, + encode-phys, and + encode-int. Of these two triples, the first describes the window - pane used to map server partition (the + pane used to map server partition (the designated management partition) memory, the second is the - window pane through which the client partition + window pane through which the client partition (the platform partition) maps its memory that it makes available to the server partition. @@ -13307,13 +13657,13 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Y - Standard property name specifying the interrupt source + 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 + 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 + 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 + edge triggered. The interrupt source number being the value returned by the H_XIRR or H_IPOLL hcall(). @@ -13336,14 +13686,14 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne See Definition Column - Property name, to define the package’s dma address + 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 + 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 + dma address size format cannot be derived using the method described in the definition for the - “ibm,#dma-size-cells” - property in + “ibm,#dma-size-cells” + property in section on System Bindings. @@ -13355,39 +13705,39 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne See Definition Column - Property name, to define the package’s dma address + 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 + 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 + dma address format cannot be derived using the method described in the definition for the - “ibm,#dma-address-cells” - property in + “ibm,#dma-address-cells” + property in section on System Bindings.
- +
- +
Virtual Asynchronous Services Interface (VASI) - - The PAPR 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. + 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 + 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: - + @@ -13399,173 +13749,173 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - +
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 + + 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 + property, see ) - each representing a specific high level operation such as an + 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 + 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. + 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 + 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 + #Opens field of the capabilities string, see ). - - VASI streams and individual service sessions may be in + + 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 + + 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). + 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. 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 + 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 + 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 + 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. + 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 + 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 + + 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 + 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 + + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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, + 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 + 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 + 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 + the VASI virtual IOA, while deregistering the VASI virtual IOA CRQ does the same for all of the VASI virtual IOA service sessions. - + - R1-R1--1. - For the VASI option: The platform - must implement the Reliable Command/Response Transport option (See + For the VASI option: The platform + must implement the Reliable Command/Response Transport option (See ). - + - R1-R1--2. - For the VASI option: The storage + 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” + 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 + tree node of the VASI virtual IOA Open Firmware device tree node. - + - R1-R1--3. - For the VASI option: Firmware must + For the VASI option: Firmware must not modify the first 8 bytes (Buffer Correlator field) of a VASI data buffer. - + - R1-R1--4. - For the VASI option: Immediately following + 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-R1--5. - For the VASI option: The VASI Download - Request Specifier must be formatted as per + For the VASI option: The VASI Download + Request Specifier must be formatted as per . - + - R1-R1--6. - For the VASI option: The VASI Operation - Request Specifier must be formatted as per + For the VASI option: The VASI Operation + Request Specifier must be formatted as per . @@ -13573,13 +13923,13 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne
VASI Download Request Specifier - - The VASI Download Request Specifier is presented in + + The VASI Download Request Specifier is presented in . - The VASI Download Request Specifier is used with the VASI Download Request + The VASI Download Request Specifier is used with the VASI Download Request message see . - +
VASI Download Request Specifier structure @@ -13593,115 +13943,115 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne
- - + +
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 + + 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 + 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 + 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 + 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 “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 + 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 + 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 + that were not transferred (Residual value of all ones indicates Residual field overflow). - Sequential writes deliver the input stream of bytes to the + 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 + 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). + 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 + 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 + 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 + 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 + 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 + 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 + The “Hardware” status code indicates a failure due to any hardware problem including physical I/O. - The “Invalid Buffer Correlator” status code is reserved + The “Invalid Buffer Correlator” status code is reserved for failure to find the operation buffer. - The “Invalid VASI Operation Request Specifier” status + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 @@ -13721,7 +14071,7 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne
VASI CRQ Message Definition (Normative) - + For the VASI interface, all CRQ messages are defined to use the following base format: @@ -13770,9 +14120,9 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne Format/Transport Event Code - For Valid Command Response Entries, see + For Valid Command Response Entries, see . - For Transport Event Codes see + For Transport Event Codes see . @@ -13807,10 +14157,10 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne - R1-R1--1. - For the VASI option: The format byte of VASI + For the VASI option: The format byte of VASI CRQ messages must be as defined in . @@ -14033,13 +14383,13 @@ hcall ( const uint64 H_FREE_VTERM, /* Break connection between server and partne
- + - R1-R1--2. - For the VASI option: The status byte + 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. . @@ -14115,7 +14465,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Invalid buffer length: Either the buffer is less than the - minimum useful buffer size or it does not match one of the first + minimum useful buffer size or it does not match one of the first “ibm,#buffer-pools” sizes that were added. @@ -14257,280 +14607,280 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
VASI Request/Response Pairs - + - R1-R1--1. For the VASI option: The platform must validate the format byte in all VASI messages that it receives. - + - R1-R1--2. - For the VASI option: + For the VASI option: The platform must initiate the processing of VASI messages in the order received on a given CRQ. - + - R1-R1--3. - For the VASI option: + 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 + is “Unused”, “Reserved”, “VASI Operation Request”, or a response other than “VASI Operation Response”, the platform must declare the format byte invalid. - + - R1-R1--4. - For the VASI option: + 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 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” + to a one and the status byte with the “Invalid Format” status code, and discard the received CRQ message. - + - R1-R1--5. - For the VASI option: + For the VASI option: The platform must fill in all reserved fields in VASI messages that it generates with zeros. - + - R1-R1--6. - For the VASI option: + 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-R1--7. - For the VASI option: + For the VASI option: The VASI Exchange Capabilities message must be as defined in . - + - R1-R1--8. - For the VASI option: - The VASI Open message must be as defined in + For the VASI option: + The VASI Open message must be as defined in . - + - R1-R1--9. - For the VASI option: - The platform must process the VASI Open Request message per the semantics described in + For the VASI option: + The platform must process the VASI Open Request message per the semantics described in . - + - R1-R1--10. - For the VASI option: - The VASI Close message must be as defined in + For the VASI option: + The VASI Close message must be as defined in . - + - R1-R1--11. - For the VASI option: - The platform must process the VASI Close Request message per the semantics described in + For the VASI option: + The platform must process the VASI Close Request message per the semantics described in . - + - R1-R1--12. - For the VASI option: - The VASI Add Buffer message must be as defined in + For the VASI option: + The VASI Add Buffer message must be as defined in . - + - R1-R1--13. - For the VASI option: - The platform must process the VASI Add Buffer Request message per the semantics described in + For the VASI option: + The platform must process the VASI Add Buffer Request message per the semantics described in . - + - R1-R1--14. - For the VASI option: - The VASI Free Buffer message must be as defined in + For the VASI option: + The VASI Free Buffer message must be as defined in . - + - R1-R1--15. - For the VASI option: - The platform must process the VASI Free Buffer Request message per the semantics described in + For the VASI option: + The platform must process the VASI Free Buffer Request message per the semantics described in . - + - R1-R1--16. - For the VASI option: - The platform must process the VASI Download Request message per the semantics described in + For the VASI option: + The platform must process the VASI Download Request message per the semantics described in . - + - R1-R1--17. - For the VASI option: - The VASI Download message must be as defined in + For the VASI option: + The VASI Download message must be as defined in . - + - R1-R1--18. - For the VASI option: - The platform must process the VASI Operation Response message per the semantics described in + For the VASI option: + The platform must process the VASI Operation Response message per the semantics described in . - + - R1-R1--19. - For the VASI option: - The VASI Operation message must be as defined in + For the VASI option: + The VASI Operation message must be as defined in . - + - R1-R1--20. - For the VASI option: - The platform must process the VASI State Request message per the semantics described in + For the VASI option: + The platform must process the VASI State Request message per the semantics described in . - + - R1-R1--21. - For the VASI option: - The VASI State message must be as defined in + For the VASI option: + The VASI State message must be as defined in . - + - R1-R1--22. - For the VASI option: - The platform must process the VASI Progress Request message per the semantics described in + For the VASI option: + The platform must process the VASI Progress Request message per the semantics described in . - + - R1-R1--23. - For the VASI option: - The VASI Progress message must be as defined in + For the VASI option: + The VASI Progress message must be as defined in . - + - R1-R1--24. - For the VASI option: - The platform must process the VASI Signal Request message per the semantics described in + For the VASI option: + The platform must process the VASI Signal Request message per the semantics described in . - + - R1-R1--25. - For the VASI option: - The VASI Signal message must be as defined in + For the VASI option: + The VASI Signal message must be as defined in . - + - R1-R1--26. - For the VASI option: + 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 + 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 @@ -14538,8 +14888,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 @@ -14547,7 +14897,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Hardware - +
Format of the VASI Exchange Capabilities CRQ elements @@ -14677,20 +15027,20 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. - +
VASI Open - + The VASI Open Command message, see , - indicates to the hypervisor that the originator VASI device driver is prepared to provide + 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: @@ -14712,7 +15062,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Invalid Service Specifier: Either reserved value or service not defined for this VASI stream. - + Semantics for VASI Open Request Message: @@ -14748,8 +15098,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Respond with Success. - - + +
Format of the VASI Open CRQ elements @@ -14763,20 +15113,20 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
VASI Close - + The VASI Close Command message, see , - requests the receiver to close the indicated BOTTOM instance of the VASI stream. + 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: @@ -14789,7 +15139,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Invalid BOTTOM - + Semantics for VASI Close Request Message: @@ -14810,8 +15160,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Free queued buffers and deallocate the control structures associated with the BOTTOM parameter, then respond Success. - - + +
Format of the VASI Close CRQ elements @@ -14825,18 +15175,18 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
VASI Add Buffer - - The VASI Add Buffer Command message, see + + 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 + 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 @@ -14847,7 +15197,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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: @@ -14866,7 +15216,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Invalid Buffer Length - + Semantics for VASI Add Buffer Request Message: @@ -14884,7 +15234,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 + 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”. @@ -14900,7 +15250,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Else select an unassigned buffer pool, and assign its length to match the length field of the Buffer Descriptor. - + @@ -14908,8 +15258,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 @@ -14923,13 +15273,13 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
VASI Free Buffer - - The VASI Free Buffer Command message, see + + 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 @@ -14940,8 +15290,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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: @@ -14960,7 +15310,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Empty - + Semantics for VASI Free Buffer Request Message: @@ -14987,8 +15337,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 @@ -15002,23 +15352,23 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
VASI Download - - The VASI Download Command message, see + + The VASI Download Command message, see - requests the hypervisor to process the VASI Download data buffer specified by the + 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: @@ -15040,7 +15390,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Invalid VASI Download data - + Semantics for VASI Download Request Message: @@ -15058,7 +15408,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 + 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”. @@ -15074,8 +15424,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 @@ -15089,12 +15439,12 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
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 @@ -15104,10 +15454,10 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 + 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: @@ -15132,7 +15482,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. End of File - + Semantics for VASI Operation Response Message: @@ -15150,8 +15500,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 @@ -15165,22 +15515,22 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
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 + 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: @@ -15196,7 +15546,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Invalid Signal Code - + Semantics for processing the VASI Signal Request Message: @@ -15214,20 +15564,20 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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 + 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 + 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” + 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 @@ -15241,20 +15591,20 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
VASI State - - The VASI virtual IOA generates a VASI State Request message, see + + 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 . @@ -15281,8 +15631,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Mark the VASI stream state transition complete. - - + +
Format of the VASI State CRQ elements @@ -15296,13 +15646,13 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
VASI Progress - - The VASI Progress Command message, see + + 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” @@ -15311,7 +15661,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. 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: @@ -15327,7 +15677,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Invalid Service Specifier - + Semantics for VASI Progress Request Message: @@ -15360,8 +15710,8 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. - - + +
Format of the VASI Progress CRQ elements @@ -15375,13 +15725,13 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721.
- +
VASI Virtual IOA Device Tree - + Properties of the VASI Node in a Partition @@ -15471,12 +15821,12 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Y - Property name specifying the unique and + Property name specifying the unique and persistent location code associated with this virtual IOA - presented as an encoded array as with - encode-string. + presented as an encoded array as with + encode-string. The value shall be of the form specified in - information on + information on Virtual Card Connector Location Codes. @@ -15488,15 +15838,15 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Y - Standard property name per IEEE 1275 specifying the + Standard property name per IEEE 1275 specifying the register addresses, used as the unit address (unit - ID), associated with this virtual IOA presented as + 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 + “#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). @@ -15508,11 +15858,11 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Y - Property name specifying the DMA window + 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, + encode-phys, and encode-int respectively. @@ -15524,13 +15874,13 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Y - Standard property name specifying the interrupt source + 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 + 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 + 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 + edge triggered. The interrupt source number being the value returned by the H_XIRR or H_IPOLL hcall(). @@ -15553,13 +15903,13 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. N - Property name, to define the package’s dma address + 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 + 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” + “ibm,#dma-size-cells” + property is missing, the default value is the + “#size-cells” property for the parent package. @@ -15571,13 +15921,13 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. N - Property name, to define the package’s dma address + 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 + 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” + “ibm,#dma-address-cells” + property is missing, the default value is the + “#address-cells” property for the parent package. @@ -15589,7 +15939,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Y - Property name to define number, encoded as with + Property name to define number, encoded as with encode-int of different data buffer size pools supported by the VASI virtual IOA service sessions. @@ -15603,7 +15953,7 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Y - Property name to define the size, in bytes, of the VASI virtual IOA CRQ; encoded as with + Property name to define the size, in bytes, of the VASI virtual IOA CRQ; encoded as with encode-int. @@ -15615,39 +15965,39 @@ able 252‚ “VASI Reliable CRQ Response Status Values‚” on page 721. Y - Property name to define the number of simultaneous + 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 + 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. @@ -15700,36 +16050,36 @@ hcall ( const uint64 H_DONOR_OPERATION, /* Use my processor to perform platform expected waiting time). - + - R1-R1--1. - For the VASI option: + For the VASI option: The platform must implement the H_DONOR_OPERATION hcall() following - the syntax and semantics of + the syntax and semantics of . - +
- +
H_VASI_SIGNAL - - This hcall() signals the condition specified by the “signal code” + + 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 + 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 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 + 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 - , + 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, + If the “signal_code” is valid for the current VASI stream state, initiate the processing defined for the “signal_code”; else return H_NOOP. @@ -15981,27 +16331,27 @@ hcall ( const uint64 H_VASI_SIGNAL, /* Signal the VASI operation stream of */ - R1-R1--1. - For the VASI option: + 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 + Else enter the value of the VASI state variable (see ) for the indicated stream into R4 and return H_Success @@ -16039,22 +16389,22 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - R1-R1--1. - For the VASI option: - The platform must implement the H_VASI_STATE hcall() following the syntax and semantics of + 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. @@ -16106,7 +16456,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + Download commands to give source platform paging requests. See . @@ -16121,7 +16471,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + the Mover partition to deliver to the source platform.See . @@ -16133,7 +16483,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 3 - VASI device will be used to handle CMO paging requests See + VASI device will be used to handle CMO paging requests See . @@ -16141,30 +16491,30 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - +
Partition Migration - + - defines the VASI Services for Partition Migration for use in the VASI Open CRQ request, as defined in + defines the VASI Services for Partition Migration for use in the VASI Open CRQ request, as defined in . - + Requirements: - + - R1-R1--1. For the Partition Migration Option: - If any partition code uses the value of the processor PVR to modify its operation, to ensure + 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-R1--2. For the Partition Migration Option: @@ -16175,20 +16525,20 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ with “Completed”. - + - R1-R1--3. For the Partition Migration Option: To maintain the platform capability to perform live firmware - updates, the OS must call the + updates, the OS must call the ibm,activate-firmware RTAS service after waking from a migration suspension. - + - R1-R1--4. For the Partition Migration Option: @@ -16196,9 +16546,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ ). - + - R1-R1--5. For the Partition Migration Option: @@ -16206,9 +16556,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ data in its VASI Download data buffers. - + - R1-R1--6. For the Partition Migration Option: @@ -16217,9 +16567,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ H_DONOR_OPERATION with TOP/BOTTOMs associated with each migration (VASI Stream ID). - + - R1-R1--7. For the Partition Migration Option: @@ -16227,9 +16577,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ a VASI Download command, it must transition the associated VASI stream to the “Aborted” state. - + - R1-R1--8. For the Partition Migration Option: @@ -16238,20 +16588,20 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - + 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 + 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 @@ -16313,10 +16663,10 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */
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 @@ -16476,17 +16826,17 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */
- - + +
Partition Hibernation - + - R1-R1--1. For the Partition Hibernation Option: @@ -16494,9 +16844,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ reconfiguration operations are complete prior to signaling suspension of the partition. - + - R1-R1--2. For the Partition Hibernation Option: @@ -16505,9 +16855,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ code, it must reread the PVR value and be prepared to remodify its operation. - + - R1-R1--3. For the Partition Hibernation Option: @@ -16518,9 +16868,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ with “Completed”. - + - R1-R1--4. For the Partition Hibernation Option: @@ -16529,9 +16879,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ RTAS service after waking from a hibernation suspension. - + - R1-R1--5. For the Partition Hibernation Option: @@ -16539,9 +16889,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ ). - + - R1-R1--6. For the Partition Hibernation Option: @@ -16550,12 +16900,12 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - +
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 @@ -16566,13 +16916,13 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + + 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 + H_VASI_STATE hcall are as defined in . - + CMO VASI Abort Reason Codes @@ -16733,7 +17083,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - +
Virtual Fibre Channel (VFC) using NPIV N_Port ID Virtualization (NPIV) is part of the Fibre Channel (FC) @@ -16746,7 +17096,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Command/Response Transport and Logical Remote DMA of the Synchronous VIO Infrastructure to service I/O requests for code running in a client partition. The client partition appears to enjoy the services of its own FC - adapter (see + adapter (see ) with a WWPN visible to the FC fabric. The terms server and client partitions refer to platform partitions that are respectively servers and clients of requests, usually I/O @@ -16757,25 +17107,25 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ The VFC model makes use of Remote DMA which is built upon the architecture specified in the following sections: - + - + - + - +
VFC and NPIV General This section contains an informative outline of the architectural intent of the use of VFC and NIPV, and it assumes the user is familiar - with + with concerning VSCSI architecture and the with the FC standards. Other implementations of the server and client partition code, consistent with this architecture, are possible @@ -16798,13 +17148,13 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ port names is beyond the scope of this architecture. The client partition’s device tree contains one or more nodes notifying the partition that it has been assigned one or more virtual - adapters. The node’s - “type” and + adapters. The node’s + “type” and “compatible” properties notify the - partition that the virtual adapter is a VFC adapter. The + partition that the virtual adapter is a VFC adapter. The unit address of the node is used by the client partition to map the virtual device(s) to the OS’s corresponding - logical representations. The + logical representations. The “ibm,my-dma-window” property communicates the size of the RTCE table window panes that the hypervisor has allocated. The node also specifies the interrupt source number that has @@ -16812,8 +17162,8 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ the RTCE range that the client partition device driver may use to map its memory for access by the server partition via Logical Remote DMA. The client partition also reads it's WWPNs from the device tree. Two WWPNs - are presented to the client in the properties - “ibm,port-wwn-1”, and + are presented to the client in the properties + “ibm,port-wwn-1”, and “ibm,port-wwn-2”, and the server tells the client, through a CRQ protocol exchange, which one of the two to use. The client partition, uses the four hcall()s associated with the Reliable @@ -16837,11 +17187,11 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ the client requests. The client partition, upon noting the device tree entry for the virtual adapter, loads the device driver associated with the value of the - + “compatible” property. The device driver, when configured and opened, allocates memory for its CRQ (an array, large enough for all possible responses, of 16 byte elements), pins the queue - and maps it into the I/O space of the RTCE window specified in the + and maps it into the I/O space of the RTCE window specified in the “ibm,my-dma-window” property using the standard kernel mapping services that subsequently use the H_PUT_TCE hcall(). The queue is then registered using the H_REG_CRQ hcall(). Next, @@ -16892,13 +17242,13 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ to use Logical Remote DMA for the virtual devices that is serving. The server partition, upon noting the device tree entry for the virtual adapter, loads the device driver associated with the value of the - + “compatible” property. 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 + 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(). Next, I/O request control blocks (within which the I/O request commands are built) are allocated, @@ -16926,7 +17276,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ the request queue element to transfer the FC IU request from the client partition’s I/O request control block to its own (allocated above), using the H_COPY_RDMA hcall() through the second window pane specified in - the + the “ibm,my-dma-window” property. The server partition’s device driver then uses kernel services, that are extended, to register the I/O request’s DMA descriptors into @@ -16945,7 +17295,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ using the H_SEND_CRQ hcall(), then recycles the resources recorded in the I/O request control block, and the block itself. The LIOBN value in the second window pane of the server - partition’s + partition’s “ibm,my-dma-window” property is intended to be an indirect reference to the RTCE table of the client partition. If, for some reason, the physical location of the client @@ -17004,7 +17354,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Contains Element Valid Bit plus Event Type Encodings (see - + ). @@ -17019,9 +17369,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Format/Transport Event Code - For Valid Command Response Entries, see + For Valid Command Response Entries, see . For Transport Event - Codes see + Codes see . @@ -17325,43 +17675,43 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - R1-R1--1. For the VFC option: The platform must implement the - Reliable Command/Response Transport option as defined in + Reliable Command/Response Transport option as defined in . - + - R1-R1--2. For the VFC option: The platform must implement the - Logical Remote DMA option as defined in + Logical Remote DMA option as defined in . - + - R1-R1--3. For the VFC option: The platform must allocate a WWPN pair for each VFC client and must present the WWPNs to the VFC clients in - their OF device tree + their OF device tree . 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 IOA’s that it has been assigned so that it can load and configure the correct device driver code. This information is provided by the OF device tree node associated - with the virtual IOA (see - and + with the virtual IOA (see + and ). @@ -17376,26 +17726,26 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - R1-R1--1. For the VFC option: The platform’s OF device - tree for client partitions must include as a child of the - /vdevice node, a node of name + tree for client partitions must include as a child of the + /vdevice node, a node of name “vfc-client” as the parent of a sub-tree representing the virtual IOAs assigned to the partition. - + - R1-R1--2. - For the VFC option: The platform’s + For the VFC option: The platform’s vfc-client OF node must contain properties as defined - in + in (other standard I/O adapter properties are permissible as appropriate).   @@ -17436,10 +17786,10 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , specifying the virtual device name, the - value shall be + value shall be “vfc-client”. @@ -17453,11 +17803,11 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , specifying the virtual device type, the value shall be - + “fcp”. @@ -17484,10 +17834,10 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , specifying the programming models that are - compatible with this virtual IOA, the value shall include + compatible with this virtual IOA, the value shall include “IBM,vfc-client”. @@ -17516,9 +17866,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Property name specifying the unique and persistent location code associated with this virtual IOA presented as an - encoded array as with + encoded array as with encode-string. The value shall be of the - form specified in + form specified in . @@ -17532,17 +17882,17 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , 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 + presented as an encoded array as with + encode-phys of length “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -17558,9 +17908,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Property name specifying the DMA window associated with this virtual IOA presented as an encoded array of three values - (LIOBN, phys, size) encoded as with - encode-int, - encode-phys, and + (LIOBN, phys, size) encoded as with + encode-int, + encode-phys, and encode-int. @@ -17576,7 +17926,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + 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 @@ -17613,9 +17963,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + definition for the “ibm,#dma-size-cells” property - in + in . @@ -17634,8 +17984,8 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + definition for the + “ibm,#dma-address-cells” property in . @@ -17650,13 +18000,13 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Property that represents one of two WWPNs assigned to - this VFC client node. This property is a - prop-encoded-array each encoded with + this VFC client node. This property is a + prop-encoded-array each encoded with encode-int. The array consists of the high order 32 bits and low order 32 bits of the WWPN such that (32 bits high | 32 bits low) is the 64 bit WWPN. The WWPN that the client is to use ( - “ibm,port-wwn-1” or + “ibm,port-wwn-1” or “ibm,port-wwn-2”) is communicated to the client by the server as part of the client-server communications protocol. @@ -17673,13 +18023,13 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Property that represents one of two WWPNs assigned to - this VFC client node This property is a - prop-encoded-array each encoded with + this VFC client node This property is a + prop-encoded-array each encoded with encode-int. The array consists of the high order 32 bits and low order 32 bits of the WWPN such that (32 bits high | 32 bits low) is the 64 bit WWPN. The WWPN that the client is to use ( - “ibm,port-wwn-1” or + “ibm,port-wwn-1” or “ibm,port-wwn-2”) is communicated to the client by the server as part of the client-server communications protocol. @@ -17690,13 +18040,13 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */
- + - R1-R1--3. - For the VFC option: The platform’s + For the VFC option: The platform’s vfc-client node must have as children the appropriate block (disk) and byte (tape) nodes. @@ -17710,26 +18060,26 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - R1-R1--1. For the VFC option: The platform’s OF device - tree for server partitions must include as a child of the - /vdevice node, a node of name + tree for server partitions must include as a child of the + /vdevice node, a node of name “vfc-server” as the parent of a sub-tree representing the virtual IOAs assigned to the partition. - + - R1-R1--2. - For the VFC option: The platform’s + For the VFC option: The platform’s vfc-server node must contain properties as defined in - + (other standard I/O adapter properties are permissible as appropriate). @@ -17773,10 +18123,10 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , specifying the virtual device name, the - value shall be + value shall be “vfc-server”. @@ -17790,10 +18140,10 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , specifying the virtual device type, the - value shall be + value shall be “fcp”. @@ -17820,10 +18170,10 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , specifying the programming models that are - compatible with this virtual IOA, the value shall include + compatible with this virtual IOA, the value shall include “IBM,vfc-server”. @@ -17852,9 +18202,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Property name specifying the unique and persistent location code associated with this virtual IOA presented as an - encoded array as with + encoded array as with encode-string. The value shall be of the - form + form . @@ -17868,17 +18218,17 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , 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 + presented as an encoded array as with + encode-phys of length “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -17895,7 +18245,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + with encode-int, encode-phys, and encode-int. Of these two triples, the @@ -17903,10 +18253,10 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ memory, the second is the window pane through which the client partition maps its memory that it makes available to the server partition. (Note the mapping between the LIOBN in the second - window pane of a server virtual IOA’s + window pane of a server virtual IOA’s “ibm,my-dma-window” property and the corresponding client IOA’s RTCE table is made - when the CRQ successfully completes registration. See + when the CRQ successfully completes registration. See for more information on window panes.) @@ -17923,7 +18273,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + 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 @@ -17974,9 +18324,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + definition for the “ibm,#dma-size-cells” property - in + in . @@ -17995,8 +18345,8 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + definition for the + “ibm,#dma-address-cells” property in . @@ -18007,7 +18357,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */
- +
Virtual Network Interface Controller (VNIC) This section defines a Virtual Network Interface Controller (VNIC) @@ -18026,19 +18376,19 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ The VNIC model makes use of Remote DMA which is built upon the architecture specified in the following sections: - + - + - + - + The use of Remote DMA has implications that the physical NIC be able to do some of its own vitualization. For example, for an Ethernet adapter, @@ -18069,12 +18419,12 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ architecture. The client partition’s device tree contains one or more nodes notifying the partition that it has been assigned one or more virtual - adapters. The node’s - “type” and + adapters. The node’s + “type” and “compatible” properties notify the partition that the virtual adapter is a VNIC. The unit address of the node is used by the client partition to map the virtual device(s) to the - OS’s corresponding logical representations. The + OS’s corresponding logical representations. The “ibm,my-dma-window” property communicates the size of the RTCE table window panes that the hypervisor has allocated. The node also specifies the interrupt source number that has @@ -18089,11 +18439,11 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ sub-CRQs necessary for the operations of the VNIC. The client partition, upon noting the device tree entry for the virtual adapter, loads the device driver associated with the value of the - + “compatible” property. The device driver, when configured and opened, allocates memory for its CRQ (an array, large enough for all possible responses, of 16 byte elements), pins the queue - and maps it into the I/O space of the RTCE window specified in the + and maps it into the I/O space of the RTCE window specified in the “ibm,my-dma-window” property using the standard kernel mapping services that subsequently use the H_PUT_TCE hcall(). The queue is then registered using the H_REG_CRQ hcall(). Next, @@ -18120,7 +18470,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ can be supported on the client side. The client allocates memory for the first sub-CRQ (an array, large enough for all possible responses, of 32 byte elements), pins the queue and maps it into the I/O space of the RTCE - window specified in the + window specified in the “ibm,my-dma-window” property using the standard kernel mapping services that subsequently use the H_PUT_TCE hcall(). The queue is then registered using the H_REG_SUB_CRQ hcall(). @@ -18128,7 +18478,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ the H_REG_SUB_CRQ hcall() indicates that the resources allocated to the client for sub-CRQs for the virtual IOA have already been allocated (H_Resource returned). Interrupt numbers for the Sub-CRQs that have been - registered, are returned by the H_REG_SUB_CRQ hcall() (See + registered, are returned by the H_REG_SUB_CRQ hcall() (See ). Once all the CRQs and Sub-CRQs are setup, the communications between the client and server device drivers may commence for purposes of @@ -18144,57 +18494,57 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ - R1-R1--1. For the VNIC option: The platform must implement the - Reliable Command/Response Transport option as defined in + Reliable Command/Response Transport option as defined in . - + - R1-R1--2. For the VNIC option: The platform must implement the - Subordinate CRQ Transport option as defined in + Subordinate CRQ Transport option as defined in . - + - R1-R1--3. For the VNIC option: The platform must implement the - Logical Remote DMA option as defined in + Logical Remote DMA option as defined in . - + - R1-R1--4. For the VNIC option: The platform’s OF device - tree for client partitions must include as a child of the - /vdevice node, at least one node of name + tree for client partitions must include as a child of the + /vdevice node, at least one node of name “vnic”. - + - R1-R1--5. - For the VNIC option: The platform’s - vnic OF node must contain properties as defined in + For the VNIC option: The platform’s + vnic OF node must contain properties as defined in (other standard I/O adapter properties are permissible as appropriate). @@ -18246,7 +18596,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ YValue = “ibm,vnic-server” - Standard property name per + Standard property name per , specifying the virtual device name. @@ -18264,9 +18614,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ N - Standard property name per + Standard property name per , specifying the - virtual device type, the value shall be + virtual device type, the value shall be “network”. @@ -18299,7 +18649,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ YValue includes: “ibm,vnic-server” - Standard property name per + Standard property name per , specifying the programming models that are compatible with this virtual IOA. @@ -18350,16 +18700,16 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Standard property name per + Standard property name per , specifying the unit address (unit ID) associated with this virtual IOA presented as - an encoded array as with - encode-phys of length + an encoded array as with + encode-phys of length “#address-cells” value shall be - 0xwhatever (virtual + 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 + zero cells (does not exist) as determined by the value of the “#size-cells” property). @@ -18378,19 +18728,19 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Property name specifying the DMA window associated with this virtual IOA presented as an encoded array of one or more sets of three values (triplet) - (LIOBN, phys, size) encoded as with - encode-int, - encode-phys, and + (LIOBN, phys, size) encoded as with + encode-int, + encode-phys, and encode-int. For the vnic-server the two tripples describe two window panes: - the first describes the window pane used to map server partition memory; - the second is the window pane through which the client partition maps - its memory that it makes available to the server partition. - (Note: the mapping between - the LIOBN in the second window pane of a server virtual IOA’s - “ibm,my-dma-window” - property and the corresponding client IOA’s RTCE table is made when the - CRQ successfully completes registration. See + the first describes the window pane used to map server partition memory; + the second is the window pane through which the client partition maps + its memory that it makes available to the server partition. + (Note: the mapping between + the LIOBN in the second window pane of a server virtual IOA’s + “ibm,my-dma-window” + property and the corresponding client IOA’s RTCE table is made when the + CRQ successfully completes registration. See .) @@ -18409,7 +18759,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + 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 @@ -18452,9 +18802,9 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + definition for the “ibm,#dma-size-cells” property - in + in . @@ -18476,8 +18826,8 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ 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 + definition for the + “ibm,#dma-address-cells” property in . @@ -18494,7 +18844,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ NA - Standard property name per + Standard property name per , specifying the locally administered MAC addresses are denoted by having the low order two bits of the high order byte being 0b10. @@ -18513,7 +18863,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ NA - Standard property name per + Standard property name per , specifying the initial MAC address (may be changed by a VNIC CRQ command). @@ -18532,8 +18882,8 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ NA - Standard property name as per - . + Standard property name as per + . Reports possible types of “network” the device can support. @@ -18551,8 +18901,8 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ NA - Standard property name as per - . + Standard property name as per + . Reports the type of “network” this device is supporting. @@ -18570,7 +18920,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ NA - Standard property name per + Standard property name per , to indicate maximum packet size. @@ -18588,7 +18938,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ NA - Standard property name per + Standard property name per , to indicate network address length. @@ -18621,8 +18971,8 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Vendor unique property name to define the physical device - virtual function upon which the vnic-server runs. The value is + Vendor unique property name to define the physical device + virtual function upon which the vnic-server runs. The value is that of the “ibm,loc-code” property of the physical device virtual function. @@ -18638,7 +18988,7 @@ hcall ( const uint64 H_VASI_STATE, /* Return the state of the VASI service */ Y - Vendor unique property that represents the operational + Vendor unique property that represents the operational mode in which the vnic-server runs.