sdbusdriver.h

2443 wince5.0 bsp, source code

//
// Copyright (c) Microsoft Corporation.  All rights reserved.
//
//
// Use of this source code is subject to the terms of the Microsoft end-user
// license agreement (EULA) under which you licensed this SOFTWARE PRODUCT.
// If you did not accept the terms of the EULA, you are not authorized to use
// this source code. For a copy of the EULA, please see the LICENSE.RTF on your
// install media.
//

// Copyright (c) 2002 BSQUARE Corporation.  All rights reserved.
// DO NOT REMOVE --- BEGIN EXTERNALLY DEVELOPED SOURCE CODE ID 40973--- DO NOT REMOVE

// Bus driver definitions

#include "SDCardDDK.h"
#include <SDHCD.h>
#include "SDCardApi.h"
#include "SDWorkItem.h"
#include "SDEnum.h"
#include "SDBusRequest.h"
#include <CReg.hxx>

#ifndef _SDCARD_BUSDRIVER_DEFINED
#define _SDCARD_BUSDRIVER_DEFINED


// base registry key for the SDCARD driver
#define SDCARD_SDMEMORY_CLASS_REG_PATH  TEXT("\\Drivers\\SDCARD\\ClientDrivers\\Class\\SDMemory_Class")
#define SDCARD_MMC_CLASS_REG_PATH       TEXT("\\Drivers\\SDCARD\\ClientDrivers\\Class\\MMC_Class")
#define SDCARD_CUSTOM_DEVICE_REG_PATH   TEXT("\\Drivers\\SDCARD\\ClientDrivers\\Custom")
#define SDCARD_SDIO_CLASS_REG_PATH      TEXT("\\Drivers\\SDCARD\\ClientDrivers\\Class\\SDIO_Class")

#define SDCARD_THREAD_PRIORITY_KEY      TEXT("ThreadPriority")
#define SDCARD_REQUEST_LIST_DEPTH_KEY   TEXT("RequestListDepth")
#define SDCARD_REQUEST_RETRY_KEY        TEXT("RequestRetryCount")

#define SDCARD_CLOCK_RATE_OVERRIDE     TEXT("SDClockRateOverride")
#define SDCARD_INTERFACE_MODE_OVERRIDE TEXT("SDInterfaceOverride")
#define SDCARD_INTERFACE_OVERRIDE_1BIT 0
#define SDCARD_INTERFACE_OVERRIDE_4BIT 1


#define SDCARD_DEFAULT_REQUEST_LIST_DEPTH   32
#define DEFAULT_THREAD_PRIORITY             100
#define DEFAULT_MEMORY_TAGS                 6
#define DEFAULT_MESSAGE_ENTRIES             7
#define DEFAULT_REFCOUNT_WAIT               100
#define DEFAULT_MAX_WAIT_COUNT              20
#define DEFAULT_BUS_REQUEST_RETRY_COUNT     3
#define DEVICE_CLEANUP_POLLING_INTERVAL     100
#define POWER_RESUME_POLLING_INTERVAL       1000
#define POWER_RESUME_DELAY_INTERVAL         2000


// typdef for the current slot state
typedef enum SD_SLOT_STATE {
    SlotInactive = 0,    // slot is inactive
    SlotIdle,            // slot is idle (after power up)
    Ready,               // the slot is ready, the client driver now has control
    SlotDeviceEjected,   // the device is being ejected
    SlotInitFailed       // slot initialization failed
} *PSD_SLOT_STATE;


typedef struct SDBUS_HC_CONTEXT *PSDBUS_HC_CONTEXT;

// slot context , one per slot
typedef struct SDBUS_HC_SLOT_CONTEXT : SDCARD_HC_SLOT_INFO {
    PSDBUS_HC_CONTEXT           pHostController;   // the host controller this slot belongs to
    SD_DEVICE_HANDLE            hDevice;           // handle to the device occupying this slot
    SD_SLOT_STATE               SlotState;         // slot state
    DWORD                       SlotIndex;         // the slot index
    SD_REQUEST_QUEUE            RequestQueue;      // request queue for this slot
    PVOID                       pWorkItem;         // work item 
    DWORD                       Flags;             // flags
} *PSDBUS_HC_SLOT_CONTEXT;

// the following bits are for flags field in the slot context
#define SD_SLOT_FLAG_SDIO_INTERRUPTS_ENABLED   0x00000001

#define IS_SLOT_SDIO_INTERRUPT_ON(pSlot) ((pSlot)->Flags & SD_SLOT_FLAG_SDIO_INTERRUPTS_ENABLED)
#define FLAG_SD_SLOT_INTERRUPTS_ON(pSlot) ((pSlot)->Flags |= SD_SLOT_FLAG_SDIO_INTERRUPTS_ENABLED)
#define FLAG_SD_SLOT_INTERRUPTS_OFF(pSlot) ((pSlot)->Flags &= ~SD_SLOT_FLAG_SDIO_INTERRUPTS_ENABLED)


// host controller context
typedef struct SDBUS_HC_CONTEXT : SDCARD_HC_CONTEXT {
    DWORD                    dwSig;                  // signature of structure
    LIST_ENTRY               ListEntry;              // hc list pointers
    DWORD                    dwHCNumber;             // hc number
    PVOID                    pSystemContext;         // system context
    DWORD                    NumberOfSlots;          // number of slots
    SDBUS_HC_SLOT_CONTEXT    SlotList[1];            // beginning of slot list array
} *PSDBUS_HC_CONTEXT;

#define SDHCGetSlotContext(pHc, Index)      &((pHc)->SlotList[Index])  


// the card registers
typedef struct SDCARD_CARD_REGISTERS {
    UCHAR   OCR[SD_OCR_REGISTER_SIZE];          // SD OCR
    UCHAR   IO_OCR[SD_IO_OCR_REGISTER_SIZE];    // IO OCR
    UCHAR   CID[SD_CID_REGISTER_SIZE];          // CID
    UCHAR   CSD[SD_CSD_REGISTER_SIZE];          // CSD
    UCHAR   SCR[SD_SCR_REGISTER_SIZE];          // SCR
} *PSDCARD_CARD_REGISTERS;


// typedef for work item callback
typedef VOID (*PSD_BUS_WORK_ITEM_FUNC) (PVOID);

// SDIO common information (shared by all I/O functions)
typedef struct SDIO_COMMON_INFORMATION {
    UCHAR                   CCCRRev;              // CCCE/SDIO Revision (common for all functions)   
    UCHAR                   SDSpec;               // SD Spec version register
    UCHAR                   CardCapability;       // card capability (common for all functions)
    DWORD                   CommonCISPointer;     // common CIS pointer for this function
    USHORT                  ManufacturerID;       // 16 bit manufacturer ID  (common) 
    USHORT                  CardID;               // 16 bit cardID     (common)
    PWCHAR                  pProductInformation;  // storage for the product information string (common)
    UCHAR                   CCCRShadowIntEnable;  // shadowed interrupt enable register (Parent Only)
    UCHAR                   CCCRShadowIOEnable;   // shadowed I/O enable register (Parent Only)
} *PSDIO_COMMON_INFORMATION;

// SDIO information for each I/O function
typedef struct SDIO_INFORMATION {
    UCHAR                    Function;             // function number
    UCHAR                    DeviceCode;           // device interface code for this function
    DWORD                    CISPointer;           // CIS pointer for this function
    DWORD                    CSAPointer;           // CSA pointer for this function
    PWCHAR                   pFunctionInformation; // storage for the function information string
    PSD_INTERRUPT_CALLBACK   pInterruptCallBack;   // for SDIO devices the interrupt callback
    PSDIO_COMMON_INFORMATION pCommonInformation;   // common information (parent only)
    BOOL                     fWUS;                 // Wake up supported?
} *PSDIO_INFORMATION;

// SD/SDIO/MMC specific information
typedef struct SDMMC_INFORMATION {
    ULONG   DataAccessWriteClocks;    // total clocks required for the write to finish  
    ULONG   DataAccessReadClocks;     // total access delay in clocks for the first byte transferred in a read
    BOOL    CardIsLocked;             // card is locked
} *PSDMMC_INFORMATION;

// SD Card information structure
typedef struct SDCARD_INFORMATION {
    SDIO_INFORMATION    SDIOInformation;    // SDIO information
    SDMMC_INFORMATION   SDMMCInformation;   // SD/SDIO/MMC information
} *PSDCARD_INFORMATION;

// the device context definition returned as the SD_DEVICE_HANDLE
typedef struct SDCARD_DEVICE_CONTEXT {
    // pGetDeviceFunctions is deprecated, but needs to stay as a
    // pointer type for legacy reasons.
    PVOID                   pvReserved;           // reserved (DO NOT CHANGE THIS LOCATION)
    HINSTANCE               hDriver;              // handle to the device driver DLL (DO NOT CHANGE THIS LOCATION)
    DWORD                   dwSig;                // signature of structure
    PSDBUS_HC_SLOT_CONTEXT  pSlot;                // the slot this device is on
    LONG                    ReferenceCount;       // this object's reference count
    TCHAR                   ClientName[MAX_SDCARD_CLIENT_NAME]; // client name
    DWORD                   ClientFlags;          // flags set by the client driver
    SDCARD_DEVICE_TYPE      DeviceType;           // device type
    CSdDeviceFolder        *pDeviceFolder;        // device folder
    PVOID                   pDeviceContext;       // device specific context
    PSD_SLOT_EVENT_CALLBACK pSlotEventCallBack;   // slot event callback
    SD_CARD_RCA             RelativeAddress;      // card's relative address
    SDCARD_CARD_REGISTERS   CachedRegisters;      // cached registers
    DWORD                   OperatingVoltage;     // current operating voltage
    PVOID                   pSystemContext;       // system context
    SDCARD_INFORMATION      SDCardInfo;           // information for SD Card (based on type)
    CRITICAL_SECTION        DeviceCritSection;    // device instance critical section for interlocking between functions
    SD_CARD_INTERFACE       CardInterface;        // card's current interface
    SDCARD_DEVICE_CONTEXT  *pNext;                // next device in chain for multifunction devices
    SDCARD_DEVICE_CONTEXT  *pParentDevice;        // parent device (for synchronization)
} *PSDCARD_DEVICE_CONTEXT;

// Signature of SDCARD_DEVICE_CONTEXT structure
#define VALID_DEVICE_CONTEXT_SIG 'cDdS' // SdDc

BOOL ValidateClientHandle(PSDCARD_DEVICE_CONTEXT pDevice);


// synchronous request information
typedef struct SD_SYNCH_REQUEST_INFO {
    HANDLE                 hWaitEvent;         // wait object
    PSD_COMMAND_RESPONSE   pResponse;          // response buffer pointer from caller
    SD_COMMAND_RESPONSE    TempResponse;       // temp response buffer 
    SD_API_STATUS          Status;             // completion status
} *PSD_SYNCH_REQUEST_INFO;

// helpful macros
#define CLIENT_HANDLES_RETRY(pDevice)   ((pDevice)->ClientFlags & SD_CLIENT_HANDLES_RETRY)
#define SDDCGetClientDeviceFromHandle(handle) ((PSDCARD_DEVICE_CONTEXT)(handle))
#define SDDCGetClientName(pDevice)            (pDevice)->ClientName
#define SDDCAcquireDeviceLock(pDevice)         EnterCriticalSection(&((pDevice)->DeviceCritSection));
#define SDDCReleaseDeviceLock(pDevice)         LeaveCriticalSection(&((pDevice)->DeviceCritSection));
#define SDDCIncrementRefCount(pDevice)     InterlockedIncrement(&((pDevice)->ReferenceCount));
#define SDDCDecrementRefCount(pDevice)     \
{ \
    DEBUG_CHECK(((pDevice)->ReferenceCount != 0),(TEXT("Reference Count decremented past zero!"))); \
    InterlockedDecrement(&((pDevice)->ReferenceCount)); \
}

#define IS_DEVICE_MULTIFUNCTION(pDevice) \
    (((pDevice)->pParentDevice != (pDevice)) || (NULL != (pDevice)->pNext))

#define SDDCGetRefCount(pDevice) (pDevice)->ReferenceCount

// bus request System Flags
#define SD_BUS_REQUEST_BUSY                 0x00000100      // bus request is in the HC
#define SD_BUS_REQUEST_NON_CANCELABLE       0x00000200      // bus request is non-cancelable
#define SD_BUS_REQUEST_COMPLETING           0x00000400      // bus request is being processed in dispatcher
#define SYSTEM_FLAGS_RETRY_COUNT_MASK       0x000000FF


#define SD_REQUEST_MARK_BUSY(p) ((p)->SystemFlags |= SD_BUS_REQUEST_BUSY)
#define IS_SD_REQUEST_BUSY(p)   ((p)->SystemFlags & SD_BUS_REQUEST_BUSY)

#define SD_REQUEST_MARK_NON_CANCELABLE(p) ((p)->SystemFlags |= SD_BUS_REQUEST_NON_CANCELABLE)
#define SD_REQUEST_MARK_CANCELABLE(p)     ((p)->SystemFlags &= ~SD_BUS_REQUEST_NON_CANCELABLE)
#define IS_SD_REQUEST_CANCELABLE(p)       (!((p)->SystemFlags & SD_BUS_REQUEST_NON_CANCELABLE))

#define SD_REQUEST_MARK_COMPLETING(p) ((p)->SystemFlags |= SD_BUS_REQUEST_COMPLETING)
#define IS_REQUEST_COMPLETING(p)      ((p)->SystemFlags & SD_BUS_REQUEST_COMPLETING)

// macros for manipulating the retry count
#define SDRequestGetRetryCount(pRequest) \
    ((pRequest)->SystemFlags & SYSTEM_FLAGS_RETRY_COUNT_MASK)

#define SDRequestSetRetryCount(pRequest, Value) \
{ \
    (pRequest)->SystemFlags &= ~SYSTEM_FLAGS_RETRY_COUNT_MASK;          \
    (pRequest)->SystemFlags |= (Value & SYSTEM_FLAGS_RETRY_COUNT_MASK); \
}

#define SDDecrementRetryCount(pRequest) \
{ \
    ULONG retryCount; \
    retryCount = SDRequestGetRetryCount(pRequest); \
    DEBUGCHK(retryCount != 0); \
    retryCount--; \
    SDRequestSetRetryCount(pRequest, retryCount); \
}


// macro to check for the slot to be ready
_inline SD_API_STATUS CheckSlotReady(PSDBUS_HC_SLOT_CONTEXT pSlot) {

    if ((SlotIdle != pSlot->SlotState) && (Ready != pSlot->SlotState)) {
        if (SlotDeviceEjected == pSlot->SlotState) {
            DEBUGMSG(SDCARD_ZONE_WARN, (TEXT("SDCard: Device in Slot:%d is about to be removed. Rejecting Request \n"), pSlot->SlotIndex));    
            return SD_API_STATUS_DEVICE_REMOVED;
        } else {
            DEBUG_CHECK(FALSE,(TEXT("SubmitBusRequest: Slot is not ready. Current slot state is %d \n"),pSlot->SlotState ));
            return SD_API_STATUS_UNSUCCESSFUL;
        }