systemsoftware
/
Linux-Architecture-Reference
30
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add H_VIOCTL subfunctions for VNIC failover support

Browse Source 
Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
pull/2/head
Jeff Scheel 4 years ago committed by Leonardo Bras
parent d22fb5eecb
commit 51d830d912
1 changed files with 2599 additions and 2249 deletions
Show Stats Download Patch File Download Diff File

352
Virtualization/ch_virtual_io.xml
Unescape Escape View File

@ -2626,6 +2626,70 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
</para>
</entry>
</row>
<row>
<entry>
<para>0x18</para>
</entry>
<entry>
<para>VNIC_SERVER_STATUS</para>
</entry>
<entry>
<para>For VNIC servers</para>
</entry>
<entry>
<para>
<xref linkend="sec_vnic_server_status_subfunction_semantics" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x19</para>
</entry>
<entry>
<para>GET_SESSION_TOKEN</para>
</entry>
<entry>
<para>For VNIC clients</para>
</entry>
<entry>
<para>
<xref linkend="sec_get_session_token_subfunction_semantics" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x1A</para>
</entry>
<entry>
<para>SESSION_ERROR_DETECTED</para>
</entry>
<entry>
<para>For VNIC clients</para>
</entry>
<entry>
<para>
<xref linkend="sec_session_error_detected_subfunction_semantics" />
</para>
</entry>
</row>
<row>
<entry>
<para>0x1B</para>
</entry>
<entry>
<para>GET_VNIC_SERVER_INFO</para>
</entry>
<entry>
<para>For VNIC servers</para>
</entry>
<entry>
<para>
<xref linkend="sec_get_vnic_server_info_subfunction_semantics" />
</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
@ -3341,8 +3405,294 @@ hcall ( const unit64 H_VIOCTL, /* Query/Set behaviors for the virtual IOA */
</listitem>
</itemizedlist>
</section>
</section>

<section xml:id="sec_vnic_server_status_subfunction_semantics">
<title>VNIC_SERVER_STATUS Subfunction Semantics</title>

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

<itemizedlist>
<listitem>
<para>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.</para>
</listitem>

<listitem>
<para>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.</para>
</listitem>

<listitem>
<para>Validate that parm-3 is zero, else return H_Parameter.</para>
</listitem>

<listitem>
<para>If the CRQ for the server adapter has not yet been registered,
return H_State.</para>
</listitem>

<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>

<section xml:id="sec_get_session_token_subfunction_semantics">
<title>GET_SESSION_TOKEN Subfunction Semantics</title>

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

<note><para>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.</para></note>

<itemizedlist>
<listitem>
<para>Validate that parm-1, parm-2, and parm-3 are 0, else return
H_Parameter.</para>
</listitem>

<listitem>
<para>Return H_Success, with the session token in R4.</para>
</listitem>
</itemizedlist>
</section>

<section xml:id="sec_session_error_detected_subfunction_semantics">
<title>SESSION_ERROR_DETECTED Subfunction Semantics</title>

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

<note><para>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.</para></note>

<itemizedlist>
<listitem>
<para>parm-1 is a VNIC session token. This token should be obtained
from the GET_SESSION_TOKEN vioctl subfunction.</para>
</listitem>

<listitem>
<para>Validate that parm-2 and parm-3 are 0, else return H_Parameter.</para>
</listitem>

<listitem>
<para>Validate that the session token parameter corresponds to the current
VNIC session, else return H_State.</para>
</listitem>

<listitem>
<para>Validate that the active server status is Operational, else return
H_Constrained.</para>
</listitem>

<listitem>
<para>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.</para>
</listitem>

<listitem>
<para>If the client successfully failed over to another backing device
as a result of this subfunction call, return H_Success.</para>
</listitem>
</itemizedlist>
</section>

<section xml:id="sec_get_vnic_server_info_subfunction_semantics">
<title>GET_VNIC_SERVER_INFO Subfunction Semantics</title>

<para>This subfunction is used to fetch information about a VNIC server
adapter.</para>

<itemizedlist>
<listitem>
<para>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
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>
property.</para>
</listitem>

<listitem>
<para>Validate that parm-2 and parm-3 are 0, else return H_Parameter.</para>
</listitem>

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

<informaltable frame="all" pgwide="1">
<tgroup cols="4">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="10*" align="center" />
<colspec colname="c4" colwidth="60*" />
<thead>
<row>
<entry>
<para><emphasis role="bold">Field</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Byte Offset</emphasis></para>
</entry>
<entry>
<para><emphasis role="bold">Size</emphasis></para>
</entry>
<entry align="center">
<para><emphasis role="bold">Description</emphasis></para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Version</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>The format version of the provided information.
The first supported version is 1.</para>
</entry>
</row>
<row>
<entry>
<para>Active</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Boolean value describing whether or not this server
adapter is currently the active server for the client
adapter it is mapped to.
<itemizedlist spacing="compact">
<listitem>
<para>0x0 - The server is not currently active.</para>
</listitem>
<listitem>
<para>0x1 - The server is currently the active backing
device for the client.</para>
</listitem>
</itemizedlist>
</para>
</entry>
</row>
<row>
<entry>
<para>Status</para>
</entry>
<entry>
<para>16</para>
</entry>
<entry>
<para>8</para>
</entry>
<entry>
<para>Enumeration value corresponding to the current
virtual adapter status.

<itemizedlist spacing="compact">
<listitem>
<para>0x1 - Operational - The server adapter is working
as expected.</para>
</listitem>
<listitem>
<para>0x2 - LinkDown - The SR-IOV backing device's
physical link is down.</para>
</listitem>
<listitem>
<para>0x3 - AdapterError - SR-IOV adapter is undergoing
EEH.</para>
</listitem>
<listitem>
<para>0x4 - PoweredOff - The virtual server adapter
or its hosting partition is powered off.</para>
</listitem>
<listitem>
<para>0x5 - NetworkError - VNIC client detected a network
issue with this adapter.</para>
</listitem>
<listitem>
<para>0x6 - Unresponsive - The hypervisor is not reliably
receiving VNIC_SERVER_STATUS vioctl calls from the VNIC
server.</para>
</listitem>
</itemizedlist>

</para>
</entry>
</row>
<row>
<entry>
<para>Priority</para>
</entry>
<entry>
<para>24</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>The current priority of this server adapter. Lower
values take precedence over larger values.</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>25</para>
</entry>
<entry>
<para>7</para>
</entry>
<entry>
<para>This field is reserved and must be zero.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>

<listitem>
<para>Return H_Success.</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>

<section xml:id="dbdoclet.50569348_94955">

Write Preview
Loading…
Cancel
Save