469 lines
12 KiB
C
469 lines
12 KiB
C
/*++
|
|
|
|
Copyright (c) 2002 Microsoft Corporation
|
|
|
|
Module Name:
|
|
|
|
ntddsd.h
|
|
|
|
Abstract:
|
|
|
|
This is the include file that defines the SD (aka Secure Digital)
|
|
bus driver interface.
|
|
|
|
|
|
--*/
|
|
|
|
#ifndef _NTDDSDH_
|
|
#define _NTDDSDH_
|
|
|
|
#if _MSC_VER > 1000
|
|
#pragma once
|
|
#endif
|
|
|
|
#if _MSC_VER >= 1200
|
|
#pragma warning(push)
|
|
#endif
|
|
|
|
//
|
|
// Disable warning: named type definition in parentheses
|
|
//
|
|
|
|
#pragma warning(disable:4201)
|
|
|
|
|
|
#include <sddef.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
//
|
|
// Use this version in the interface_data structure
|
|
//
|
|
|
|
#define SDBUS_INTERFACE_VERSION 0x101
|
|
|
|
//
|
|
// Prototype of the callback routine which is called for SDIO
|
|
// devices to reflect device interrupts.
|
|
//
|
|
|
|
__drv_functionClass(SDBUS_CALLBACK_ROUTINE)
|
|
__drv_sameIRQL
|
|
__drv_maxIRQL(DISPATCH_LEVEL)
|
|
typedef
|
|
VOID
|
|
SDBUS_CALLBACK_ROUTINE(
|
|
__in PVOID CallbackRoutineContext,
|
|
__in ULONG InterruptType
|
|
);
|
|
|
|
typedef SDBUS_CALLBACK_ROUTINE *PSDBUS_CALLBACK_ROUTINE;
|
|
|
|
|
|
#define SDBUS_INTTYPE_DEVICE 0
|
|
|
|
//
|
|
// The interface parameters structure is passed to the InitializeInterface
|
|
// function in the SDBUS_INTERFACE_STANDARD
|
|
//
|
|
|
|
typedef struct _SDBUS_INTERFACE_PARAMETERS {
|
|
USHORT Size;
|
|
USHORT Reserved;
|
|
|
|
//
|
|
// Points to next lower device object in the device stack.
|
|
//
|
|
PDEVICE_OBJECT TargetObject;
|
|
|
|
//
|
|
// This flag indicates whether the caller expects any device
|
|
// interrupts from the device.
|
|
//
|
|
BOOLEAN DeviceGeneratesInterrupts;
|
|
|
|
//
|
|
// The caller can specify here the IRQL at which the callback
|
|
// function is entered. If this value is TRUE, the callback will
|
|
// be entered at DPC level. If this value is FALSE, the callback
|
|
// will be entered at passive level.
|
|
//
|
|
// Specifying TRUE will generally lower latency time of the interrupt
|
|
// delivery, at the cost of complicating the device driver, which
|
|
// must then deal with running at different IRQLs.
|
|
//
|
|
BOOLEAN CallbackAtDpcLevel;
|
|
|
|
//
|
|
// When an IO device interrupts, the SD bus driver will generate a
|
|
// callback to this routine. The caller must supply this pointer if
|
|
// the field DeviceGeneratesInterrupts was set to TRUE;
|
|
//
|
|
PSDBUS_CALLBACK_ROUTINE CallbackRoutine;
|
|
|
|
//
|
|
// The caller can specify here a context value which will be passed
|
|
// to the device interrupt callback routine.
|
|
//
|
|
PVOID CallbackRoutineContext;
|
|
|
|
} SDBUS_INTERFACE_PARAMETERS, *PSDBUS_INTERFACE_PARAMETERS;
|
|
|
|
//
|
|
// Prototype of function used to initialize the the interface once
|
|
// it has been opened.
|
|
//
|
|
|
|
__checkReturn
|
|
__drv_sameIRQL
|
|
__drv_maxIRQL(DISPATCH_LEVEL)
|
|
typedef
|
|
NTSTATUS
|
|
(*PSDBUS_INITIALIZE_INTERFACE_ROUTINE)(
|
|
__in PVOID Context,
|
|
__in PSDBUS_INTERFACE_PARAMETERS InterfaceParameters
|
|
);
|
|
|
|
|
|
//
|
|
// Prototype of routine that the function driver must call
|
|
// when the function driver has completed its interrupt processing
|
|
//
|
|
|
|
__drv_sameIRQL
|
|
__drv_maxIRQL(DISPATCH_LEVEL)
|
|
typedef
|
|
NTSTATUS
|
|
(*PSDBUS_ACKNOWLEDGE_INT_ROUTINE)(
|
|
__in PVOID Context
|
|
);
|
|
|
|
|
|
//
|
|
// SDBUS_INTERFACE_STANDARD
|
|
//
|
|
// Interface Data structure used in the SdBusOpenInterface call. This
|
|
// structure defines the communication path between the SD function
|
|
// driver and the bus driver.
|
|
//
|
|
|
|
DEFINE_GUID( GUID_SDBUS_INTERFACE_STANDARD, 0x6bb24d81L, 0xe924, 0x4825, 0xaf, 0x49, 0x3a, 0xcd, 0x33, 0xc1, 0xd8, 0x20 );
|
|
|
|
|
|
typedef struct _SDBUS_INTERFACE_STANDARD {
|
|
USHORT Size;
|
|
USHORT Version;
|
|
//
|
|
// Interface Context
|
|
//
|
|
// This context pointer is filled in by the bus driver during the call
|
|
// to SdBusOpenInterface(). This data must be passed as a parameter to
|
|
// the other interface functions.
|
|
//
|
|
PVOID Context;
|
|
|
|
//
|
|
// Interface Reference/Dereference maintain the interface's reference
|
|
// count. The reference count is automatically incremented to 1 when
|
|
// the interface is opened. The caller must dereference the interface
|
|
// under the following circumstances:
|
|
// a) the function driver receives a query_remove IRP
|
|
// b) the function driver receives a surprise_remove IRP
|
|
// c) the function driver receives a remove IRP without either a
|
|
// query_remove or a surprise_remove.
|
|
//
|
|
// In all cases, the function driver should dereference the interface
|
|
// before passing the respective IRP down to the bus driver.
|
|
//
|
|
PINTERFACE_REFERENCE InterfaceReference;
|
|
PINTERFACE_DEREFERENCE InterfaceDereference;
|
|
|
|
//
|
|
// After the interface has been opened, the bus driver will have filled
|
|
// in the pointer to the following routine which allows the function
|
|
// driver to set the parameters of the interface.
|
|
//
|
|
|
|
PSDBUS_INITIALIZE_INTERFACE_ROUTINE InitializeInterface;
|
|
|
|
//
|
|
// NTSTATUS SdBusAcknowledgeInterrupt(InterfaceContext)
|
|
//
|
|
// This routine is filled in by the call to SdBusOpenInterface(),
|
|
// and is used by the function driver to indicate when processing
|
|
// of an IO device interrupt is complete.
|
|
//
|
|
// When an IO function of an SD device asserts an interrupt, the bus
|
|
// driver will disable that interrupt to allow I/O operations to be
|
|
// sent to the device at a reasonable IRQL (that is, <=DISPATCH_LEVEL).
|
|
//
|
|
// When the function driver's callback routine, which is equivalent to
|
|
// an ISR, is done clearing the function's interrupt, this routine should
|
|
// be called to re-enable the IRQ for card interrupts.
|
|
//
|
|
// Callers must be running at IRQL <= DISPATCH_LEVEL.
|
|
//
|
|
// Returns STATUS_UNSUCCESSFUL if the InterfaceContext pointer is invalid.
|
|
//
|
|
|
|
PSDBUS_ACKNOWLEDGE_INT_ROUTINE AcknowledgeInterrupt;
|
|
|
|
} SDBUS_INTERFACE_STANDARD, *PSDBUS_INTERFACE_STANDARD;
|
|
|
|
|
|
//
|
|
// SdBusOpenInterface()
|
|
//
|
|
// This routine establishes a connection to the SD bus driver.
|
|
// It should be called in the AddDevice routine with the FDO for
|
|
// the device stack is created.
|
|
//
|
|
// If STATUS_SUCCESS is returned, then the InterfaceData structure
|
|
// is filled in with valid function pointers and an interface context
|
|
// parameter. The context pointer must be used in all other SD bus
|
|
// driver calls.
|
|
//
|
|
// Callers must be running at IRQL < DISPATCH_LEVEL.
|
|
//
|
|
|
|
__checkReturn
|
|
__drv_sameIRQL
|
|
__drv_maxIRQL(APC_LEVEL)
|
|
NTSTATUS
|
|
SdBusOpenInterface(
|
|
__in PDEVICE_OBJECT Pdo,
|
|
__out PSDBUS_INTERFACE_STANDARD InterfaceStandard,
|
|
__in USHORT Size,
|
|
__in USHORT Version
|
|
);
|
|
|
|
|
|
//
|
|
// Definitions for properties used in Get/Set Property requests
|
|
//
|
|
// The bus driver version where any given property was introduced is
|
|
// indicated as a comment to the right of the property. Note that the
|
|
// property to retrieve the version was not introduced until v2.0.
|
|
// Callers can determine the bus driver is at version 1.0 by looking
|
|
// for a STATUS_INVALID_PARAMETER return from an get property call on
|
|
// SDP_BUS_DRIVER_VERSION.
|
|
//
|
|
|
|
typedef enum {
|
|
SDP_MEDIA_CHANGECOUNT = 0, // v1.0 ULONG
|
|
SDP_MEDIA_STATE, // v1.0 SDPROP_MEDIA_STATE
|
|
SDP_WRITE_PROTECTED, // v1.0 BOOLEAN
|
|
SDP_FUNCTION_NUMBER, // v1.0 UCHAR
|
|
SDP_FUNCTION_TYPE, // v2.0 SDBUS_FUNCTION_TYPE
|
|
SDP_BUS_DRIVER_VERSION, // v2.0 USHORT
|
|
SDP_BUS_WIDTH, // v2.0 UCHAR
|
|
SDP_BUS_CLOCK, // v2.0 ULONG
|
|
SDP_BUS_INTERFACE_CONTROL, // v2.0 UCHAR
|
|
SDP_HOST_BLOCK_LENGTH, // v2.0 USHORT
|
|
SDP_FUNCTION_BLOCK_LENGTH, // v2.0 USHORT
|
|
SDP_FN0_BLOCK_LENGTH, // v2.0 USHORT
|
|
SDP_FUNCTION_INT_ENABLE, // v2.0 BOOLEAN
|
|
} SDBUS_PROPERTY;
|
|
|
|
//
|
|
// Bus driver versions
|
|
//
|
|
|
|
#define SDBUS_DRIVER_VERSION_1 0x100
|
|
#define SDBUS_DRIVER_VERSION_2 0x200
|
|
|
|
//
|
|
// Media states defined for SDP_MEDIA_STATE
|
|
//
|
|
|
|
typedef enum {
|
|
SDPMS_NO_MEDIA = 0,
|
|
SDPMS_MEDIA_INSERTED
|
|
} SDPROP_MEDIA_STATE;
|
|
|
|
|
|
//
|
|
// Values defined for SDP_FUNCTION_TYPE
|
|
//
|
|
|
|
typedef enum {
|
|
SDBUS_FUNCTION_TYPE_UNKNOWN = 0,
|
|
SDBUS_FUNCTION_TYPE_SDIO,
|
|
SDBUS_FUNCTION_TYPE_SD_MEMORY,
|
|
SDBUS_FUNCTION_TYPE_MMC_MEMORY,
|
|
} SDBUS_FUNCTION_TYPE;
|
|
|
|
#define IsTypeMemory(type) ((type == SDBUS_FUNCTION_TYPE_SD_MEMORY) || \
|
|
(type == SDBUS_FUNCTION_TYPE_MMC_MEMORY))
|
|
#define IsTypeIo(type) (type == SDBUS_FUNCTION_TYPE_SDIO)
|
|
|
|
|
|
//
|
|
// Data structures for request packets
|
|
//
|
|
|
|
typedef enum {
|
|
SDRF_GET_PROPERTY,
|
|
SDRF_SET_PROPERTY,
|
|
SDRF_DEVICE_COMMAND
|
|
} SD_REQUEST_FUNCTION;
|
|
|
|
|
|
//
|
|
// SDBUS_REQUEST_PACKET
|
|
//
|
|
// This structure specifies parameters for individual requests
|
|
// and commands sent to the bus driver by SdBusSubmitRequest()
|
|
//
|
|
|
|
typedef struct _SDBUS_REQUEST_PACKET {
|
|
|
|
//
|
|
// specifies the parameters for the operation, and how they
|
|
// are interpreted
|
|
//
|
|
SD_REQUEST_FUNCTION RequestFunction;
|
|
|
|
//
|
|
// These context fields are provided for the optional use of the caller.
|
|
// They are not referenced by the bus driver
|
|
//
|
|
PVOID UserContext[3];
|
|
|
|
//
|
|
// Information from the operation. Its usage is equivalent to
|
|
// the Irp->IoStatus.Information field. For example, the length
|
|
// of data transmitted for read/write operations will be filled
|
|
// in here by the bus driver.
|
|
//
|
|
ULONG_PTR Information;
|
|
|
|
//
|
|
// Response data and length is returned by the device. Maximum
|
|
// returned is 16 bytes. The content of this field is defined
|
|
// in the SD spec.
|
|
//
|
|
union {
|
|
UCHAR AsUCHAR[16];
|
|
ULONG AsULONG[4];
|
|
SDRESP_TYPE3 Type3;
|
|
} ResponseData;
|
|
UCHAR ResponseLength;
|
|
|
|
//
|
|
// Parameters to the individual functions
|
|
//
|
|
union {
|
|
|
|
//
|
|
// The property functions allow the caller to control aspects of
|
|
// bus driver operation.
|
|
//
|
|
|
|
struct {
|
|
SDBUS_PROPERTY Property;
|
|
PVOID Buffer;
|
|
ULONG Length;
|
|
} GetSetProperty;
|
|
|
|
//
|
|
// DeviceCommand is the 'pipe' that allows SD device codes and arguments
|
|
// to be executed. These codes are either defined in the SD spec,
|
|
// can be based per device class, or can also be proprietary.
|
|
//
|
|
|
|
struct {
|
|
SDCMD_DESCRIPTOR CmdDesc;
|
|
ULONG Argument;
|
|
PMDL Mdl;
|
|
ULONG Length;
|
|
} DeviceCommand;
|
|
|
|
} Parameters;
|
|
|
|
|
|
} SDBUS_REQUEST_PACKET, *PSDBUS_REQUEST_PACKET;
|
|
|
|
|
|
|
|
//
|
|
// SdBusSubmitRequest()
|
|
// SdBusSubmitRequestAsync()
|
|
//
|
|
// These routines send SD request packets to the bus driver. The SubmitRequest
|
|
// version is synchronous, and must be called at IRQL < DISPATCH_LEVEL. The
|
|
// SubmitRequestAsync version is asynchronous, and the user must supply an IRP
|
|
// and completion routine.
|
|
//
|
|
// Arguments:
|
|
//
|
|
// InterfaceContext - this is the context pointer returned by the
|
|
// SdBusOpenInterface() call.
|
|
//
|
|
// Packet - The parameters of the request are specified in this
|
|
// SDBUS_REQUEST_PACKET, which is allocated by the caller.
|
|
//
|
|
// Irp - The passed IRP will be used to transfer the request
|
|
// packet to the bus driver. It can either be a new irp
|
|
// allocated by the caller just for this request, or it can
|
|
// also be an IRP the caller is processing. The packet will
|
|
// be placed in the Parameters.Others.Argument1 of the IRP.
|
|
//
|
|
// CompletionRoutine- When the request is completed by the bus driver, this
|
|
// completion routine will be called.
|
|
//
|
|
// UserContext - This context will be passed to the specified CompletionRoutine
|
|
//
|
|
// Notes:
|
|
//
|
|
// Callers of SdBusSubmitRequest must be running at IRQL < DISPATCH_LEVEL.
|
|
// Callers of SdBusSubmitRequestAsync must be running at IRQL <= DISPATCH_LEVEL.
|
|
//
|
|
|
|
__checkReturn
|
|
__drv_sameIRQL
|
|
__drv_maxIRQL(APC_LEVEL)
|
|
NTSTATUS
|
|
SdBusSubmitRequest(
|
|
__in PVOID InterfaceContext,
|
|
__in PSDBUS_REQUEST_PACKET Packet
|
|
);
|
|
|
|
|
|
__checkReturn
|
|
__drv_sameIRQL
|
|
__drv_maxIRQL(DISPATCH_LEVEL)
|
|
NTSTATUS
|
|
SdBusSubmitRequestAsync(
|
|
__in PVOID InterfaceContext,
|
|
__in PSDBUS_REQUEST_PACKET Packet,
|
|
__in PIRP Irp,
|
|
__in PIO_COMPLETION_ROUTINE CompletionRoutine,
|
|
__in PVOID UserContext
|
|
);
|
|
|
|
|
|
//
|
|
// IoControlCode values used in this interface. There normally should be no
|
|
// need to use these values directly, as SDBUS.LIB provides the support routines
|
|
// which issue these IOCTLs to the bus driver.
|
|
//
|
|
//
|
|
|
|
#define IOCTL_SDBUS_BASE FILE_DEVICE_CONTROLLER
|
|
#define IOCTL_SD_SUBMIT_REQUEST CTL_CODE(IOCTL_SDBUS_BASE, 3100, METHOD_NEITHER, FILE_ANY_ACCESS)
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#if _MSC_VER >= 1200
|
|
#pragma warning(pop)
|
|
#endif
|
|
|
|
#endif
|
|
|