<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=US-ASCII">
<META NAME="Generator" CONTENT="MS Exchange Server version 5.5.2654.45">
<TITLE>RE: [Openib-windows] [RFC] IRP-based verbs</TITLE>
</HEAD>
<BODY>
<P><FONT SIZE=2>Hi Fab,</FONT>
</P>
<P><FONT SIZE=2>Before we get down to the details of your proposal we would like to clarify our general opinion in this area.</FONT>
</P>
<P><FONT SIZE=2>1) Enabling asynchronous calls to the command interface is something that we believe that should be done in the mid-term schedule.</FONT></P>
<P><FONT SIZE=2>2) We don't see any way to achieve this goal without significant changes to the low level driver (currently under rewrite). A preliminary version of the driver should be available on November.</FONT></P>
<P><FONT SIZE=2>3) We will be happy to accept patches from you that will turn all verbs (in the driver) to by asynchronous. (We will probably be able to start looking at the patches on January next year).</FONT></P>
<P><FONT SIZE=2>4) As this is a very big change to the entire stack, it seems that the stability of the stack will be harmed. Therefore, we ask that you do the change in a different branch.</FONT></P>
<P><FONT SIZE=2>5) Also, to my understanding, this change will cause changes in IBAL, and all ULPs. As a result I believe that we should make a design review of the changes so that we make sure to get all the benefits from it.</FONT></P>
<P><FONT SIZE=2>6) We should probably schedule a phone meeting to make sure that we all understand each other.</FONT>
</P>
<P><FONT SIZE=2>Thanks</FONT>
<BR><FONT SIZE=2>Tzachi</FONT>
</P>
<P><FONT SIZE=2>>-----Original Message-----</FONT>
<BR><FONT SIZE=2>>From: Fab Tillier [<A HREF="mailto:ftillier@silverstorm.com">mailto:ftillier@silverstorm.com</A>]</FONT>
<BR><FONT SIZE=2>>Sent: Saturday, September 10, 2005 3:22 AM</FONT>
<BR><FONT SIZE=2>>To: 'Tzachi Dar'; openib-windows@openib.org</FONT>
<BR><FONT SIZE=2>>Subject: RE: [Openib-windows] [RFC] IRP-based verbs</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>> From: Tillier, Fabian</FONT>
<BR><FONT SIZE=2>>> Sent: Friday, September 09, 2005 3:14 PM</FONT>
<BR><FONT SIZE=2>>></FONT>
<BR><FONT SIZE=2>>> Ok, here's a shot at defining a direct-call kernel interface that</FONT>
<BR><FONT SIZE=2>>supports</FONT>
<BR><FONT SIZE=2>>> verb calls at DISPATCH. Right now it's just open and close CA.</FONT>
<BR><FONT SIZE=2>>Currently,</FONT>
<BR><FONT SIZE=2>>> the interface requires an input IRP. We could change this to be</FONT>
<BR><FONT SIZE=2>>optional,</FONT>
<BR><FONT SIZE=2>>> in which case the implementation could block for IRQL < DISPATCH_LEVEL,</FONT>
<BR><FONT SIZE=2>>and</FONT>
<BR><FONT SIZE=2>>> fail the call for IRQL >= DISPATCH_LEVEL if it would block. Making the</FONT>
<BR><FONT SIZE=2>>IRP</FONT>
<BR><FONT SIZE=2>>> optional complicates the implementation a little, which is why I didn't</FONT>
<BR><FONT SIZE=2>>do</FONT>
<BR><FONT SIZE=2>>> it.</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>Updated with a few more functions to better illustrate what's going on.</FONT>
<BR><FONT SIZE=2>>Also,</FONT>
<BR><FONT SIZE=2>>resource creation functions now take as input an optional event dispatch</FONT>
<BR><FONT SIZE=2>>table</FONT>
<BR><FONT SIZE=2>>for up-calls to the client for notifications. Clients are free to use</FONT>
<BR><FONT SIZE=2>>either</FONT>
<BR><FONT SIZE=2>>IRP driven event notifications or callback driven.</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>Thoughts?</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>- Fab</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>> * Copyright (c) 2005 SilverStorm Technologies. All rights reserved.</FONT>
<BR><FONT SIZE=2>> *</FONT>
<BR><FONT SIZE=2>> * This software is available to you under the OpenIB.org BSD license</FONT>
<BR><FONT SIZE=2>> * below:</FONT>
<BR><FONT SIZE=2>> *</FONT>
<BR><FONT SIZE=2>> * Redistribution and use in source and binary forms, with or</FONT>
<BR><FONT SIZE=2>> * without modification, are permitted provided that the following</FONT>
<BR><FONT SIZE=2>> * conditions are met:</FONT>
<BR><FONT SIZE=2>> *</FONT>
<BR><FONT SIZE=2>> * - Redistributions of source code must retain the above</FONT>
<BR><FONT SIZE=2>> * copyright notice, this list of conditions and the following</FONT>
<BR><FONT SIZE=2>> * disclaimer.</FONT>
<BR><FONT SIZE=2>> *</FONT>
<BR><FONT SIZE=2>> * - Redistributions in binary form must reproduce the above</FONT>
<BR><FONT SIZE=2>> * copyright notice, this list of conditions and the following</FONT>
<BR><FONT SIZE=2>> * disclaimer in the documentation and/or other materials</FONT>
<BR><FONT SIZE=2>> * provided with the distribution.</FONT>
<BR><FONT SIZE=2>> *</FONT>
<BR><FONT SIZE=2>> * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,</FONT>
<BR><FONT SIZE=2>> * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF</FONT>
<BR><FONT SIZE=2>> * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND</FONT>
<BR><FONT SIZE=2>> * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS</FONT>
<BR><FONT SIZE=2>> * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN</FONT>
<BR><FONT SIZE=2>> * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN</FONT>
<BR><FONT SIZE=2>> * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE</FONT>
<BR><FONT SIZE=2>> * SOFTWARE.</FONT>
<BR><FONT SIZE=2>> *</FONT>
<BR><FONT SIZE=2>> * $Id$</FONT>
<BR><FONT SIZE=2>> */</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>#include <ntddk.h></FONT>
<BR><FONT SIZE=2>>#include <ib_defs.h></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****s* Verbs/CI_UDATA</FONT>
<BR><FONT SIZE=2>>* NAME</FONT>
<BR><FONT SIZE=2>>* CI_UDATA</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Vendor specific structure to facilitate user mode IO</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* This structure is provided to assist the vendor specific user mode</FONT>
<BR><FONT SIZE=2>>* library to exchange information with its kernel mode driver. The</FONT>
<BR><FONT SIZE=2>>* user mode InfiniBand(tm) Access Layer will call the vendor specific</FONT>
<BR><FONT SIZE=2>>* module before a call is made to the kernel mode driver. The kernel mode</FONT>
<BR><FONT SIZE=2>>* driver is expected to know the format and data in the input and output</FONT>
<BR><FONT SIZE=2>>* buffers, and copy any necessary data that must be handed to the user</FONT>
<BR><FONT SIZE=2>>* mode vendor library.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* PURPOSE</FONT>
<BR><FONT SIZE=2>>* pInputBuffer</FONT>
<BR><FONT SIZE=2>>* UVP input buffer. May overlap the output buffer.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pOutputBuffer</FONT>
<BR><FONT SIZE=2>>* UVP output buffer. NULL if no output buffer is provided.</FONT>
<BR><FONT SIZE=2>>* May overlap the input buffer.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* InputSize</FONT>
<BR><FONT SIZE=2>>* Size of UVP provided buffer. Zero if there is no input buffer.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* OutputSize</FONT>
<BR><FONT SIZE=2>>* The size of the UVP provided output buffer. Zero if no output</FONT>
<BR><FONT SIZE=2>>* buffer is provided. The kernel mode driver sets this to the exact</FONT>
<BR><FONT SIZE=2>>* size that needs to be returned to its user mode counterpart.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SOURCE</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>typedef struct _CI_UDATA</FONT>
<BR><FONT SIZE=2>>{</FONT>
<BR><FONT SIZE=2>> const VOID* __ptr64 const pInputBuffer;</FONT>
<BR><FONT SIZE=2>> VOID* __ptr64 const pOutputBuffer;</FONT>
<BR><FONT SIZE=2>> SIZE_T InputSize;</FONT>
<BR><FONT SIZE=2>> SIZE_T OutputSize;</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>} CI_UDATA;</FONT>
<BR><FONT SIZE=2>>/******/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef void IB_API</FONT>
<BR><FONT SIZE=2>>(PFN_IB_CA_FATAL_EVENT*)(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN VOID *CaContext );</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef void IB_API</FONT>
<BR><FONT SIZE=2>>(PFN_IB_CA_PORT_EVENT*)(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN VOID *CaContext,</FONT>
<BR><FONT SIZE=2>> IN const UCHAR PortNumber,</FONT>
<BR><FONT SIZE=2>> IN IB_ASYNC_EVENT Event );</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef struct _IB_CA_DISPATCH</FONT>
<BR><FONT SIZE=2>>{</FONT>
<BR><FONT SIZE=2>> PFN_IB_CA_FATAL_EVENT FatalEvent;</FONT>
<BR><FONT SIZE=2>> PFN_IB_CA_PORT_EVENT PortEvent;</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>} IB_CA_DISPATCH;</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef struct _IB_CA</FONT>
<BR><FONT SIZE=2>>{</FONT>
<BR><FONT SIZE=2>> IB_CA_DISPATCH Dispatch;</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>} IB_CA;</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiOpenCa</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Opens the HCA for client use.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiOpenCa(</FONT>
<BR><FONT SIZE=2>> IN DEVICE_OBJECT* const pHcaFdo,</FONT>
<BR><FONT SIZE=2>> IN VOID* const Context,</FONT>
<BR><FONT SIZE=2>> IN const IB_CA_DISPATCH* const Dispatch OPTIONAL,</FONT>
<BR><FONT SIZE=2>> IN OUT CI_UDATA* const pUserData,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pHcaFdo</FONT>
<BR><FONT SIZE=2>>* [in] Functional Device object of the target HCA.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Context</FONT>
<BR><FONT SIZE=2>>* [in] A pointer to a caller-supplied context for the CA instance</FONT>
<BR><FONT SIZE=2>>* being created. The HCA driver passes this value to the client's</FONT>
<BR><FONT SIZE=2>>* event callback functions. If the client will not be using event</FONT>
<BR><FONT SIZE=2>>* callbacks, this value is unused.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Dispatch</FONT>
<BR><FONT SIZE=2>>* [in] A pointer to a constant client IB_CA_DISPATCH structure. This</FONT>
<BR><FONT SIZE=2>>* structure is a dispatch table that contains pointers to the event</FONT>
<BR><FONT SIZE=2>>* callback functions for the new CA instance. Any members of the</FONT>
<BR><FONT SIZE=2>>* table can be NULL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pUserData</FONT>
<BR><FONT SIZE=2>>* [in] Descriptor for any data exchanged with the user-mode verb</FONT>
<BR><FONT SIZE=2>>* provider. The input and output buffers are shadowed by the</FONT>
<BR><FONT SIZE=2>>* access layer in non-paged pool. The HCA driver can only access</FONT>
<BR><FONT SIZE=2>>* further embedded pointers from the context of this call.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The operation completed successfully. The IoStatus.Information</FONT>
<BR><FONT SIZE=2>>* field of the IRP contains a pointer to a CA instance structure,</FONT>
<BR><FONT SIZE=2>>* IB_CA, for the new CA instance.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiCloseCa</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Closes an open instance of an HCA.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiCloseCa(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN OUT CI_UDATA* const pUserData,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pUserData</FONT>
<BR><FONT SIZE=2>>* [in] Descriptor for any data exchanged with the user-mode verb</FONT>
<BR><FONT SIZE=2>>* provider. The input and output buffers are shadowed by the</FONT>
<BR><FONT SIZE=2>>* access layer in non-paged pool. The HCA driver can only access</FONT>
<BR><FONT SIZE=2>>* further embedded pointers from the context of this call.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The CA instance was closed successfully. The IRP will be completed</FONT>
<BR><FONT SIZE=2>>* with success status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_DEVICE_BUSY</FONT>
<BR><FONT SIZE=2>>* The operation could not complete because the CA instance has</FONT>
<BR><FONT SIZE=2>>* outstanding resources allocated.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Any pending event notification IRPs will be completed with</FONT>
<BR><FONT SIZE=2>>* STATUS_CANCELLED before the function returns.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiGetCaFatalEvent</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Queues a request for HCA catastrophic error notification.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiGetCaFatalEvent(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when a local catastrophic error</FONT>
<BR><FONT SIZE=2>>* occurs on the HCA. The IRP major and minor functions as well as</FONT>
<BR><FONT SIZE=2>>* the I/O stack must be preserved when the IRP is completed. The</FONT>
<BR><FONT SIZE=2>>* Irp.RequestorMode can be used to distinguish kernel and user</FONT>
<BR><FONT SIZE=2>>clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The CA instance experienced a fatal error and should be closed.</FONT>
<BR><FONT SIZE=2>>* The IRP will be completed with success status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must set a cancel routine to allow clients to cancel</FONT>
<BR><FONT SIZE=2>>* the notification request.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* A client can queue up mutiple requests for notification. Only one</FONT>
<BR><FONT SIZE=2>>* request is completed per event. All such requests are completed with</FONT>
<BR><FONT SIZE=2>>* STATUS_CANCELLED if the IB_CA instance is closed.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiGetCaPortEvent</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Queues a requests for port event notification.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiGetCaPortEvent(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN const UCHAR PortNumber,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* PortNumber</FONT>
<BR><FONT SIZE=2>>* [in] Port number to which the notification request is targetted.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The CA instance experienced a port event. The IoStatus.Information</FONT>
<BR><FONT SIZE=2>>* member of the IRP is updated with the IB_ASYNC_EVENT value. The</FONT>
<BR><FONT SIZE=2>>IRP</FONT>
<BR><FONT SIZE=2>>* will be completed with success status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field of the IRP and the IB_ASYNC_EVENT will be returned in the</FONT>
<BR><FONT SIZE=2>>* IoStatus.Information field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must set a cancel routine to allow clients to cancel</FONT>
<BR><FONT SIZE=2>>* the notification request.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* A client can queue up mutiple requests for notification. Only one</FONT>
<BR><FONT SIZE=2>>* request is completed per event. All such requests are completed with</FONT>
<BR><FONT SIZE=2>>* STATUS_CANCELLED if the IB_CA instance is closed.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiQueryCa</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Queries an HCA for its attributes.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiQueryCa(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN const SIZE_T AttrSize,</FONT>
<BR><FONT SIZE=2>> OUT IB_CA_ATTR* const pAttr,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pAttrSize</FONT>
<BR><FONT SIZE=2>>* [in] Size of the attributes buffer referenced by the pAttr</FONT>
<BR><FONT SIZE=2>>parameter.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pAttr</FONT>
<BR><FONT SIZE=2>>* [out] CA attribute of this Host Channel adapter.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The full CA attributes, including port attributes and their GID</FONT>
<BR><FONT SIZE=2>>* and PKEY tables, were successfully copied to the attribute buffer.</FONT>
<BR><FONT SIZE=2>>* The IoStatus.Information field of the IRP is updated to indicate</FONT>
<BR><FONT SIZE=2>>* the number of bytes returned.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field and the number of bytes returned in the IoStatus.Information</FONT>
<BR><FONT SIZE=2>>* field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_BUFFER_OVERFLOW</FONT>
<BR><FONT SIZE=2>>* The operation completed but returned only partial attributes. Full</FONT>
<BR><FONT SIZE=2>>* attributes were not returned due to insufficient space. The size</FONT>
<BR><FONT SIZE=2>>* required to get the full attributes is returned in the Size field</FONT>
<BR><FONT SIZE=2>>* of the IB_CA_ATTR structure. The IoStatus.Information field of the</FONT>
<BR><FONT SIZE=2>>* IRP is updated to indicate the number of bytes returned.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_BUFFER_TOO_SMALL</FONT>
<BR><FONT SIZE=2>>* The pAttr buffer was too small to return any information. At a</FONT>
<BR><FONT SIZE=2>>* minimum, the buffer must be the 4 bytes to allow the required</FONT>
<BR><FONT SIZE=2>>* size to be returned.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_FILE_FORCED_CLOSED</FONT>
<BR><FONT SIZE=2>>* The CA is no longer functional. The IRP will be completed with</FONT>
<BR><FONT SIZE=2>>* failure status. The client must release all resources and close</FONT>
<BR><FONT SIZE=2>>* the CA as soon as possible.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiQueryPort</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Queries an HCA for one of its port attributes.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiQueryPort(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN const UCHAR PortNumber,</FONT>
<BR><FONT SIZE=2>> IN const SIZE_T AttrSize,</FONT>
<BR><FONT SIZE=2>> OUT IB_PORT_ATTR* const pAttr,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* PortNumber</FONT>
<BR><FONT SIZE=2>>* [in] 1-based port number targetted by this request.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pAttrSize</FONT>
<BR><FONT SIZE=2>>* [in] Size of the attributes buffer referenced by the pAttr</FONT>
<BR><FONT SIZE=2>>parameter.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pAttr</FONT>
<BR><FONT SIZE=2>>* [out] CA attribute of this Host Channel adapter.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The full port attributes, including the GID and PKEY tables, were</FONT>
<BR><FONT SIZE=2>>* successfully copied to the attribute buffer.</FONT>
<BR><FONT SIZE=2>>* The IoStatus.Information field of the IRP is updated to indicate</FONT>
<BR><FONT SIZE=2>>* the number of bytes returned.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field and the number of bytes returned in the IoStatus.Information</FONT>
<BR><FONT SIZE=2>>* field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_BUFFER_OVERFLOW</FONT>
<BR><FONT SIZE=2>>* The operation completed but returned only partial attributes. Full</FONT>
<BR><FONT SIZE=2>>* attributes were not returned due to insufficient space. The size</FONT>
<BR><FONT SIZE=2>>* required to get the full attributes is returned in the Size field</FONT>
<BR><FONT SIZE=2>>* of the IB_PORT_ATTR structure. The IoStatus.Information field of</FONT>
<BR><FONT SIZE=2>>* the IRP is updated to indicate the number of bytes returned.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_BUFFER_TOO_SMALL</FONT>
<BR><FONT SIZE=2>>* The pAttr buffer was too small to return any information. At a</FONT>
<BR><FONT SIZE=2>>* minimum, the buffer must be the 4 bytes to allow the required</FONT>
<BR><FONT SIZE=2>>* size to be returned.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_FILE_FORCED_CLOSED</FONT>
<BR><FONT SIZE=2>>* The CA is no longer functional. The IRP will be completed with</FONT>
<BR><FONT SIZE=2>>* failure status. The client must release all resources and close</FONT>
<BR><FONT SIZE=2>>* the CA as soon as possible.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiModifyCa</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Modify the attributes of a Channel Adapter.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiModifyCa(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN const ULONG Flags,</FONT>
<BR><FONT SIZE=2>> IN const IB_MODIFY_CA* const pModify,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Flags</FONT>
<BR><FONT SIZE=2>>* [in] Combination of IB_MODIFY_CA_FLAGS values indicating which</FONT>
<BR><FONT SIZE=2>>* fields are valid in the IB_MODIFY_CA structure.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pModify</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_MODIFY_CA structure with the fields specified</FONT>
<BR><FONT SIZE=2>>* by the Flags parameter set to the desired values.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The CA was modified successfully.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_FILE_FORCED_CLOSED</FONT>
<BR><FONT SIZE=2>>* The CA is no longer functional. The IRP will be completed with</FONT>
<BR><FONT SIZE=2>>* failure status. The client must release all resources and close</FONT>
<BR><FONT SIZE=2>>* the CA as soon as possible.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiModifyPort</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Modify the attributes of a Channel Adapter's port.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiModifyPort(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN const UCHAR PortNumber,</FONT>
<BR><FONT SIZE=2>> IN const ULONG Flags,</FONT>
<BR><FONT SIZE=2>> IN const IB_MODIFY_PORT* const pModify,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* PortNumber</FONT>
<BR><FONT SIZE=2>>* [in] 1-based port number targetted by this request.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Flags</FONT>
<BR><FONT SIZE=2>>* [in] Combination of IB_MODIFY_CA_FLAGS values indicating which</FONT>
<BR><FONT SIZE=2>>* fields are valid in the IB_MODIFY_CA structure.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pModify</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_MODIFY_CA structure with the fields specified</FONT>
<BR><FONT SIZE=2>>* by the Flags parameter set to the desired values.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The CA's port was modified successfully.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field of the IRP.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_FILE_LOCK_CONFLICT</FONT>
<BR><FONT SIZE=2>>* The requested capabilities conflict with existing capabilities.</FONT>
<BR><FONT SIZE=2>>* This can occur if multiple clients try to bits such as</FONT>
<BR><FONT SIZE=2>>* IB_PORT_CAP_IS_SM or IB_PORT_CAP_CM_SUP bits in the port</FONT>
<BR><FONT SIZE=2>>* capabilities.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_FILE_FORCED_CLOSED</FONT>
<BR><FONT SIZE=2>>* The CA is no longer functional. The IRP will be completed with</FONT>
<BR><FONT SIZE=2>>* failure status. The client must release all resources and close</FONT>
<BR><FONT SIZE=2>>* the CA as soon as possible.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef void</FONT>
<BR><FONT SIZE=2>>(PFN_IB_CQ_COMP_EVENT*)</FONT>
<BR><FONT SIZE=2>> IN VOID *CqContext );</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef void</FONT>
<BR><FONT SIZE=2>>(PFN_IB_CQ_ASYNC_EVENT*)</FONT>
<BR><FONT SIZE=2>> IN VOID *CqContext,</FONT>
<BR><FONT SIZE=2>> IN IB_ASYNC_EVENT Event );</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef struct IB_CQ_DISPATCH</FONT>
<BR><FONT SIZE=2>>{</FONT>
<BR><FONT SIZE=2>> PFN_IB_CQ_COMP_EVENT CompEvent;</FONT>
<BR><FONT SIZE=2>> PFN_IB_CQ_ASYNC_EVENT AsyncEvent;</FONT>
<BR><FONT SIZE=2>>}</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>typedef struct IB_CQ</FONT>
<BR><FONT SIZE=2>>{</FONT>
<BR><FONT SIZE=2>> IB_CQ_DISPATCH Dispatch;</FONT>
<BR><FONT SIZE=2>> ULONG NumCqes;</FONT>
<BR><FONT SIZE=2>>}</FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>></FONT>
<BR><FONT SIZE=2>>/****f* Verbs/CiCreateCq</FONT>
<BR><FONT SIZE=2>>* DESCRIPTION</FONT>
<BR><FONT SIZE=2>>* Create a Completion Queue.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* SYNOPSIS</FONT>
<BR><FONT SIZE=2>>*/</FONT>
<BR><FONT SIZE=2>>CiCreateCq(</FONT>
<BR><FONT SIZE=2>> IN IB_CA* const pCa,</FONT>
<BR><FONT SIZE=2>> IN ULONG const NumCqes,</FONT>
<BR><FONT SIZE=2>> IN VOID* const Context,</FONT>
<BR><FONT SIZE=2>> IN const IB_CQ_DISPATCH* const Dispatch OPTIONAL,</FONT>
<BR><FONT SIZE=2>> IN OUT CI_UDATA* const pUserData,</FONT>
<BR><FONT SIZE=2>> IN IRP* const pIrp );</FONT>
<BR><FONT SIZE=2>>/*</FONT>
<BR><FONT SIZE=2>>* PARAMETERS</FONT>
<BR><FONT SIZE=2>>* pCa</FONT>
<BR><FONT SIZE=2>>* [in] Pointer to an IB_CA structure previously created by a call to</FONT>
<BR><FONT SIZE=2>>* CiOpenCa.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NumCqes</FONT>
<BR><FONT SIZE=2>>* [in] Number of CQ entries requested by the consumer.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Context</FONT>
<BR><FONT SIZE=2>>* [in] A pointer to a caller-supplied context for the CQ being</FONT>
<BR><FONT SIZE=2>>* created. The HCA driver passes this value to the client's</FONT>
<BR><FONT SIZE=2>>* event callback functions. If the client will not be using event</FONT>
<BR><FONT SIZE=2>>* callbacks, this value is unused.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Dispatch</FONT>
<BR><FONT SIZE=2>>* [in] A pointer to a constant client IB_CQ_DISPATCH structure. This</FONT>
<BR><FONT SIZE=2>>* structure is a dispatch table that contains pointers to the event</FONT>
<BR><FONT SIZE=2>>* callback functions for the new CA instance. Any members of the</FONT>
<BR><FONT SIZE=2>>* table can be NULL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pUserData</FONT>
<BR><FONT SIZE=2>>* [in] Descriptor for any data exchanged with the user-mode verb</FONT>
<BR><FONT SIZE=2>>* provider. The input and output buffers are shadowed by the</FONT>
<BR><FONT SIZE=2>>* access layer in non-paged pool. The HCA driver can only access</FONT>
<BR><FONT SIZE=2>>* further embedded pointers from the context of this call.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* pIrp</FONT>
<BR><FONT SIZE=2>>* [in] IRP that will be completed when the request completes.</FONT>
<BR><FONT SIZE=2>>* The IRP major and minor functions as well as the I/O stack must</FONT>
<BR><FONT SIZE=2>>* be preserved when the IRP is completed. The Irp.RequestorMode</FONT>
<BR><FONT SIZE=2>>* can be used to distinguish kernel and user clients.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* RETURN VALUES</FONT>
<BR><FONT SIZE=2>>* STATUS_SUCCESS</FONT>
<BR><FONT SIZE=2>>* The CQ was created successfully. The IB_CQ structure is returned</FONT>
<BR><FONT SIZE=2>>* in the IoStatus.Information field of the IRP. The IB_CQ structure</FONT>
<BR><FONT SIZE=2>>* contains the actual number of CQ entries allocated for the CQ.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_PENDING</FONT>
<BR><FONT SIZE=2>>* The operation could not be completed immediately. The HCA driver</FONT>
<BR><FONT SIZE=2>>* will complete the IRP when the operation completes, at which point</FONT>
<BR><FONT SIZE=2>>* the status of the operation will be returned in the IoStatus.Status</FONT>
<BR><FONT SIZE=2>>* field and the IB_CQ structure in the IoStatus.Information field of</FONT>
<BR><FONT SIZE=2>>* the IRP. The IB_CQ structure contains the actual number of CQ</FONT>
<BR><FONT SIZE=2>>* entries allocated for the CQ.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* STATUS_FILE_FORCED_CLOSED</FONT>
<BR><FONT SIZE=2>>* The CA is no longer functional. The IRP will be completed with</FONT>
<BR><FONT SIZE=2>>* failure status. The client must release all resources and close</FONT>
<BR><FONT SIZE=2>>* the CA as soon as possible.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* Other status codes</FONT>
<BR><FONT SIZE=2>>* An error occurred. The IRP will be completed with failure status.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* NOTES</FONT>
<BR><FONT SIZE=2>>* This function can be invoked at IRQL <= DISPATCH_LEVEL.</FONT>
<BR><FONT SIZE=2>>*</FONT>
<BR><FONT SIZE=2>>* The HCA driver must call IoCallDriver for the input IRP so that it</FONT>
<BR><FONT SIZE=2>>* can call I/O complete request. The target of IoCallDriver must be</FONT>
<BR><FONT SIZE=2>>* the FDO of the HCA since the IRP will have only a single I/O stack</FONT>
<BR><FONT SIZE=2>>* location for the HCA to use. This implies that the IRP cannot be</FONT>
<BR><FONT SIZE=2>>* passed down a chain of layered drivers.</FONT>
<BR><FONT SIZE=2>>*********/</FONT>
</P>
</BODY>
</HTML>