[Openib-windows] [RFC] IRP-based verbs
Fab Tillier
ftillier at silverstorm.com
Fri Sep 9 15:13:47 PDT 2005
> From: Tzachi Dar [mailto:tzachid at mellanox.co.il]
> Sent: Friday, September 09, 2005 4:10 AM
>
> The IOCTL interface is a very complicated interface that is mainly used for
> communicating between user mode and kernel applications. Since it is so
> complicated there will probably by wrapper functions around it, so I believe
> that there will be no need to use the IOCTLs (at all) for communicating in the
> kernel.
Ok, here's a shot at defining a direct-call kernel interface that supports verb
calls at DISPATCH. Right now it's just open and close CA. Currently, the
interface requires an input IRP. We could change this to be optional, in which
case the implementation could block for IRQL < DISPATCH_LEVEL, and fail the call
for IRQL >= DISPATCH_LEVEL if it would block. Making the IRP optional
complicates the implementation a little, which is why I didn't do it.
Thoughts?
- Fab
/*
* Copyright (c) 2005 SilverStorm Technologies. All rights reserved.
*
* This software is available to you under the OpenIB.org BSD license
* below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* $Id$
*/
#include <ntddk.h>
#include <ib_defs.h>
typedef struct _IB_CA
{
UINT64 Guid;
} IB_CA;
/****s* Verbs/CI_UDATA
* NAME
* CI_UDATA
*
* DESCRIPTION
* Vendor specific structure to facilitate user mode IO
*
* This structure is provided to assist the vendor specific user mode
* library to exchange information with its kernel mode driver. The
* user mode InfiniBand(tm) Access Layer will call the vendor specific
* module before a call is made to the kernel mode driver. The kernel mode
* driver is expected to know the format and data in the input and output
* buffers, and copy any necessary data that must be handed to the user
* mode vendor library.
*
* PURPOSE
* pInputBuffer
* UVP input buffer. May overlap the output buffer.
*
* pOutputBuffer
* UVP output buffer. NULL if no output buffer is provided.
* May overlap the input buffer.
*
* InputSize
* Size of UVP provided buffer. Zero if there is no input buffer.
*
* OutputSize
* The size of the UVP provided output buffer. Zero if no output
* buffer is provided. The kernel mode driver sets this to the exact
* size that needs to be returned to its user mode counterpart.
*
* SOURCE
*/
typedef struct _CI_UDATA
{
const VOID* __ptr64 const pInputBuffer;
VOID* __ptr64 const pOutputBuffer;
SIZE_T InputSize;
SIZE_T OutputSize;
} CI_UDATA;
/******/
/****f* Verbs/CiOpenCa
* DESCRIPTION
* Opens the HCA for client use.
*
* SYNOPSIS
*/
CiOpenCa(
IN DEVICE_OBJECT* const pHcaFdo,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pHcaFdo
* [in] Functional Device object of the target HCA.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major function is IRP_MJ_DEVICE_CONTROL and minor
* function ranges between 0x800 and 0xC00. The I/O stack parameters
* are opaque to the HCA driver and should not be modified. Only the
* Tail.Overlay area of the IRP is available for HCA driver use. The
* Irp.RequestorMode can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The operation completed successfully. The IoStatus.Information
* field of the IRP contains a pointer to a CA instance structure,
* IB_CA, for the new CA instance.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
/****f* Verbs/CiCloseCa
* DESCRIPTION
* Closes an open instance of an HCA.
*
* SYNOPSIS
*/
CiCloseCa(
IN IB_CA* const pCa,
IN OUT CI_UDATA* const pUserData,
IN IRP* const pIrp );
/*
* PARAMETERS
* pCa
* [in] Pointer to a IB_CA structure previously created by a call to
* CiOpenCa.
*
* pUserData
* [in] Descriptor for any data exchanged with the user-mode verb
* provider. The input and output buffers are shadowed by the
* access layer in non-paged pool. The HCA driver can only access
* further embedded pointers from the context of this call.
*
* pIrp
* [in] IRP that will be completed when the request completes.
* The IRP major function is IRP_MJ_DEVICE_CONTROL and minor
* function ranges between 0x800 and 0xC00. The I/O stack parameters
* are opaque to the HCA driver and should not be modified. Only the
* Tail.Overlay area of the IRP is available for HCA driver use. The
* Irp.RequestorMode can be used to distinguish kernel and user clients.
*
* RETURN VALUES
* STATUS_SUCCESS
* The CA instance was closed successfully. The IRP will be completed
* with success status.
*
* STATUS_PENDING
* The operation could not be completed immediately. The HCA driver
* will complete the IRP when the operation completes, at which point
* the status of the operation will be returned in the IoStatus.Status
* field of the IRP.
*
* STATUS_DEVICE_BUSY
* The operation could not complete because the CA instance has
* outstanding resources allocated.
*
* Other status codes
* An error occurred. The IRP will be completed with failure status.
*
* NOTES
* This function can be invoked at IRQL <= DISPATCH_LEVEL.
*
* The HCA driver must call IoCallDriver for the input IRP so that it
* can call I/O complete request. The target of IoCallDriver must be
* the FDO of the HCA since the IRP will have only a single I/O stack
* location for the HCA to use. This implies that the IRP cannot be
* passed down a chain of layered drivers.
*********/
More information about the ofw
mailing list