sdcardddk.h

6410BSP3

//
// Copyright (c) Microsoft Corporation.  All rights reserved.
//
//
// Use of this sample source code is subject to the terms of the Microsoft
// license agreement under which you licensed this sample source code. If
// you did not accept the terms of the license agreement, you are not
// authorized to use this sample source code. For the terms of the license,
// please see the license agreement between you and Microsoft or, if applicable,
// see the LICENSE.RTF on your install media or the root of your tools installation.
// THE SAMPLE SOURCE CODE IS PROVIDED "AS IS", WITH NO WARRANTIES.
//

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

// Core header file for SD Card DDK

#ifndef _SDCARD_DDK_DEFINED
#define _SDCARD_DDK_DEFINED


#include <windows.h>
#include <types.h>
#include <linklist.h>
#include <ceddk.h>

#include "SDMem.h"
#include "SDCard.h"

#define SD_CSD_VERSION_CODE_1_0         0
#define SD_CSD_VERSION_CODE_2_0         1

#define SD_CSD_VERSION_CODE_SUPPORTED   SD_CSD_VERSION_CODE_2_0 
#define MMC_CSD_VERSION_CODE_SUPPORTED  2 // version 3.1
#define HSMMC_CSD_SPEC_VERSION_CODE_SUPPORTED 4 // version 4.x

#ifdef _MMC_SPEC_42_ 
// an argument value of CMD1 to support sector address mode, dual voltage 
#define OCR_SECTOR_SUPPORT    0x40FF8080 
#endif   


typedef PVOID SD_DEVICE_HANDLE;

// typedef for API Status codes
typedef LONG SD_API_STATUS;

// transfer class enum, indicates whether a bus request is read,write or a command
typedef enum { 
    SD_READ = 0,         // block read
    SD_WRITE = 1,        // block write
    SD_COMMAND = 2,      // command only
} SD_TRANSFER_CLASS;

// SDIO Read/Write Enum
typedef enum { 
    SD_IO_READ = 0, 
    SD_IO_WRITE = 1,  
} SD_IO_TRANSFER_TYPE;

// indicates Interface being used for a card
typedef enum {  
    SD_INTERFACE_SD_MMC_1BIT = 0, 
    SD_INTERFACE_SD_4BIT = 1, 
    SD_INTERFACE_MMC_8BIT = 2
} SD_INTERFACE_MODE;

#ifdef _MMC_SPEC_42_ 
typedef union {
  struct {
    ULONG sd4Bit:1;
    ULONG sdHighSpeed:1;
    ULONG hsmmc8Bit:1;
    ULONG :27;
    ULONG sdWriteProtected:1;
    ULONG sdHighCapacity:1;
  } bit;
  ULONG uInterfaceMode;
} SD_INTERFACE_MODE_EX,*PSD_INTERFACE_MODE_EX;
#else
typedef union {
    struct {
        ULONG sd4Bit:1;
        ULONG sdHighSpeed:1;
        ULONG :28;
        ULONG sdWriteProtected:1;
        ULONG sdHighCapacity:1;
    } bit;
    ULONG uInterfaceMode;
} SD_INTERFACE_MODE_EX,*PSD_INTERFACE_MODE_EX;
#endif

// enum for querying card information, some of this information is cached
typedef enum { 
    SD_INFO_REGISTER_OCR = 0,       // 32-bit OCR cached value for MMC/SDMemory Cards
    SD_INFO_REGISTER_CID,           // CID for MMC/SDMemory Cards
    SD_INFO_REGISTER_CSD,           // CSD for MMC/SDMemory Cards
    SD_INFO_REGISTER_RCA,           // RCA data type for MMC/SDMemory/SD IO Cards
    SD_INFO_REGISTER_IO_OCR,        // 24 bit IO-OCR register for SDIO Cards
    SD_INFO_CARD_INTERFACE,         // card interface for all card types
    SD_INFO_CARD_STATUS,            // card status for MMC/SD Memory cards
    SD_INFO_SDIO,                   // SDIO information (SD IO only)
    SD_INFO_HOST_IF_CAPABILITIES,   // SD Host Interface Capabilities
    SD_INFO_HOST_BLOCK_CAPABILITY,  // SD Host Block Length Capabilities
    SD_INFO_HIGH_CAPACITY_SUPPORT,  // SD Memory High Capacity
    SD_INFO_TYPE_COUNT,             // number of SD_INFO_TYPEs
    SD_INFO_CARD_INTERFACE_EX,      // CARD extension bit after 1.10
    SD_INFO_SWITCH_FUNCTION,        // SWITCH Function, Read Current Supported Function.    
#ifdef _MMC_SPEC_42_
    MMC_INFO_REGISTER_EXTCSD,       // Extended CSD register 
#endif 
} SD_INFO_TYPE;

// enum for device type
typedef enum _SDCARD_DEVICE_TYPE {
    Device_Unknown = 0,
    Device_MMC = 1,
    Device_SD_Memory = 2,
    Device_SD_IO = 3,
    Device_SD_Combo = 4  // combo is only an intermediate device type reserved only for the bus driver
#ifdef _MMC_SPEC_42_
    ,
    Device_HSMMC40 = 5,
    Device_HSMMC42 = 6
#endif
}SDCARD_DEVICE_TYPE, *PSDCARD_DEVICE_TYPE;

// enum for setting SD Card Features
typedef enum { 
    SD_IO_FUNCTION_ENABLE = 0,          // enable I/O Function, uses SD_IO_FUNCTION_ENABLE_INFO
    SD_IO_FUNCTION_DISABLE,             // disable I/O Function - no structure required
    SD_IO_FUNCTION_SET_BLOCK_SIZE,      // set the SDIO Function block size,takes a DWORD parameter
    SD_SET_DATA_TRANSFER_CLOCKS,        // set read and write data transfer clocks
    SD_SET_CARD_INTERFACE,              // set the physical card interface
    SD_SET_CLOCK_STATE_DURING_IDLE,     // set the clock state during the idle state
    SD_IS_SOFT_BLOCK_AVAILABLE,         // Determine if Soft-Block is available in the SD Bus driver.
    SD_SOFT_BLOCK_FORCE_UTILIZATION,    // Always use Soft-Block (testing use only).
    SD_SOFT_BLOCK_DEFAULT_UTILIZATON,   // Enable Soft-Block use.
    SD_CARD_SELECT_REQUEST,             // request the card to be selected
    SD_CARD_DESELECT_REQUEST,           // request the card to be deselected
    SD_CARD_FORCE_RESET,                // force the card to be reset
    SD_IS_FAST_PATH_AVAILABLE,          // Determine if Fast-Path is available in the SD Bus driver.
    SD_FAST_PATH_DISABLE,               // Disable Fast-Path use (testing use only).
    SD_FAST_PATH_ENABLE,                // Enable Fast-Path use.
    SD_IO_FUNCTION_HIGH_POWER,          // Select High Power mode for Function
    SD_IO_FUNCTION_LOW_POWER,           // Select Low Power mode for Function
    SD_INFO_POWER_CONTROL_STATE,         // Get functions power state
    SD_SET_CARD_INTERFACE_EX,           // set the physical card interface with extended structure SD_CARD_INTERFACE_EX.
    SD_SET_SWITCH_FUNCTION,             // For 1.1 Memory card to switch Function.
    SD_DMA_ALLOC_PHYS_MEM,              // Optional, Allocate DMAable Physical Memory,
    SD_DMA_FREE_PHYS_MEM                // Optional, Free DMAable Pysical Memor located by SD_DMA_ALLOC_PHYS_MEM    
} SD_SET_FEATURE_TYPE, *PSD_SET_FEATURE_TYPE;

// structure for SD_IO_FUNCTION_ENABLE card feature
typedef struct _SD_IO_FUNCTION_ENABLE_INFO{
    ULONG   ReadyRetryCount;    // number of retries to check the ready bit in the function
    ULONG   Interval;           // interval in milliseconds to check
}SD_IO_FUNCTION_ENABLE_INFO, *PSD_IO_FUNCTION_ENABLE_INFO;

// info for SD_SET_DATA_TRANSFER_CLOCKS card feature
typedef struct _SD_DATA_TRANSFER_CLOCKS {
    ULONG   ReadClocks;         // the worst case number of read clocks before read data is sent 
    ULONG   WriteClocks;        // number of clocks that busy signal can remain assrted
} SD_DATA_TRANSFER_CLOCKS, *PSD_DATA_TRANSFER_CLOCKS;

// structure for information about a card's interface
typedef struct _SD_CARD_INTERFACE {
    SD_INTERFACE_MODE   InterfaceMode;  // interface mode
    ULONG               ClockRate;      // clock rate
    BOOL                WriteProtected; // write protect flag (SD Memory cards)
} SD_CARD_INTERFACE, *PSD_CARD_INTERFACE;

// structure for information about a card's interface
typedef struct _SD_CARD_INTERFACE_EX {
    SD_INTERFACE_MODE_EX InterfaceModeEx;  // Extended interface mode
    ULONG               ClockRate;      // clock rate
    ULONG               Reserved[6];    // Reserved should be zero.
} SD_CARD_INTERFACE_EX, *PSD_CARD_INTERFACE_EX;

// structure for SDIO device information
typedef struct _SDIO_CARD_INFO{
    UCHAR   FunctionNumber;   // SDIO function number
    UCHAR   DeviceCode;       // device interface code for this function
    DWORD   CISPointer;       // CIS pointer for this function
    DWORD   CSAPointer;       // CSA pointer for this function
    UCHAR   CardCapability;   // common card capabilities
} SDIO_CARD_INFO, *PSDIO_CARD_INFO;

// structure for SD_INFO_HOST_BLOCK_CAPABILITY card information
typedef struct _SD_HOST_BLOCK_CAPABILITY{
    USHORT  ReadBlockSize;   // block size for read requests
    USHORT  WriteBlockSize;  // block size for write requests
    USHORT  ReadBlocks;      // number of blocks for each read request
    USHORT  WriteBlocks;     // number of blocks for each write request
} SD_HOST_BLOCK_CAPABILITY, *PSD_HOST_BLOCK_CAPABILITY;

// structure for SDHCAllocateDMABuffer and SDHCFreeDMABuffer
typedef struct {
    ULONG               Length;
    BOOLEAN             CacheEnabled;
    PVOID               VirtualAddress;
    PHYSICAL_ADDRESS    LogicalAddress;
} SD_HOST_ALLOC_FREE_DMA_BUFFER,*PSD_HOST_ALLOC_FREE_DMA_BUFFER;

typedef struct _SD_CARD_EXTENSION {
    union {
        struct {
            ULONG   HighCapacity:1;  // High Capacity card for 2.0.
            ULONG   Reserved:31;
        } bit;
        ULONG   ulHighCapacityValue;
    };
    ULONGLONG   ullDeviceSize;
    ULONG   Reserved[5];        // Reserved for future.
} SD_CARD_EXTENSION, *PSD_CARD_EXTENSION;
typedef struct _SD_CARD_SWITCH_FUNCTION {
    DWORD   dwSelectedFunction; // 6 function group. each one has 4 bits.
    DWORD   dwMaxCurrentAllowed;// Only allow dwMaxCurrentAllowed mA for switch to new Function
    DWORD   dwTimeOut;          // Ticks for time out the select.
    BYTE    clientData[512/8];    // Client Data which is provided by Switch function.
} SD_CARD_SWITCH_FUNCTION, *PSD_CARD_SWITCH_FUNCTION;

// enum for response types
typedef enum  _SD_RESPONSE_TYPE {
    NoResponse  = 0,
    ResponseR1  = 1,
    ResponseR1b = 2,
    ResponseR2  = 3,
    ResponseR3  = 4, 
    ResponseR4  = 5,
    ResponseR5  = 6,
    ResponseR6  = 7,
    ResponseR7  = 8
} SD_RESPONSE_TYPE, *PSD_RESPONSE_TYPE;

// fast path event callback event types
typedef enum _SD_SLOT_EVENT_TYPE {
    SDCardEjected = 1,              // card ejected
    SDCardSelected = 2,             // card selected
    SDCardDeselected = 3,           // card deselected
    SDCardBeginSelectDeselect = 4,  // Start to do Select_Deselect 
    SDCardDeselectRequest = 5,      // bus driver received card deselect request
    SDCardSelectRequest = 6         // bus driver received card select request
}SD_SLOT_EVENT_TYPE, *PSD_SLOT_EVENT_TYPE;


// maximum length of a debug string
#define MAXIMUM_DEBUG_STRING_LENGTH 384
#define MAX_KEY_NAME_LENGTH    32
#define MAX_KEY_PATH_LENGTH    256
#define MAX_SDCARD_CLIENT_NAME 32
#define MAX_FILE_NAME_LENGTH   256

// 64K debug file
#define DEFAULT_MAX_DEBUG_FILE_LENGTH 0x10000

// forward declaration
typedef struct _SD_BUS_REQUEST *PSD_BUS_REQUEST;

// typedef for bus request completion callback
typedef VOID (*PSD_BUS_REQUEST_CALLBACK) (SD_DEVICE_HANDLE,
                                          PSD_BUS_REQUEST,
                                          PVOID,
                                          DWORD);

typedef struct _SD_COMMAND_RESPONSE {
    SD_RESPONSE_TYPE ResponseType;                                  // response type
    UCHAR            ResponseBuffer[SDCARD_RESPONSE_BUFFER_BYTES];  // largest possible reponse buffer
}SD_COMMAND_RESPONSE, *PSD_COMMAND_RESPONSE;

typedef struct __PHYS_BUFF_LIST {
    PHYSICAL_ADDRESS    PhysAddr;
    UINT32              PhysLen;
} PHYS_BUFF_LIST , *PPHYS_BUFF_LIST;

// structure to identify a bus request, used to cancel/track request
typedef struct _SD_BUS_REQUEST {
    LIST_ENTRY  ListEntry;          // list entry
    SD_DEVICE_HANDLE hDevice;       // the device this request belongs to
    ULONG       SystemFlags;        // system flags
    SD_TRANSFER_CLASS TransferClass; // transfer class
    UCHAR       CommandCode;        // command code
    DWORD       CommandArgument;    // command argument 
    SD_COMMAND_RESPONSE CommandResponse;  // command response
    DWORD       RequestParam;       // optional request parameter
    SD_API_STATUS Status;           // completion status
    ULONG       NumBlocks;          // number of blocks
    ULONG       BlockSize;          // size of each block   
    DWORD       HCParam;            // host controller parameter, reserved for HC drivers
    PUCHAR      pBlockBuffer;       // buffer holding block data
    PSD_BUS_REQUEST_CALLBACK pCallback;  // callback when the request completes
    DWORD       DataAccessClocks;   // data access clocks for data transfers (READ or WRITE), reserved for HC driver
    // for reads, this is the typical clock delay for the first read data byte
    // for writes, this is the typical clock delay for the write operation to finish
    DWORD       Flags;              // request flags
    DWORD       cbSizeOfPhysList;
    PPHYS_BUFF_LIST pPhysBuffList;    
} SD_BUS_REQUEST, *PSD_BUS_REQUEST;

// request flags
#define SD_AUTO_ISSUE_CMD12     0x00000001  // automatically issue CMD12 after the command
#define SD_SDIO_AUTO_IO_ABORT   0x00000002  // (SDIO Only) automatically abort I/O using CMD52 

#ifdef _FOR_MOVI_NAND_
/**
 * Description : It means that make option request to send Cmd 23 ( SET_BLOCK_LENGTH )
 */
#define SD_MOVINAND_PRE_DEFINE  0x00000010
#endif

// unspecified access clocks 
#define SD_UNSPECIFIED_ACCESS_CLOCKS 0xFFFFFFFF

// some macros to get fields from the bus request structure
#define SD_BUS_REQUEST_RESPONSE(request) ((request)->CommandResponse)
#define SD_BUS_REQUEST_STATUS(request)   ((request)->Status)
#define SD_SYNCHRONOUS_REQUEST  0x00000004  // This is a synchronous request from the bus driver.
#define SD_SLOTRESET_REQUEST    0x00000008  // This is a request for resetting the slot

    // bus request System Flags
    //     Bits 27-0 are defined in SDBusDriver.h
#define SD_FAST_PATH_AVAILABLE  0x80000000  // Fast-Path is available for this request.
#define SD_SET_EVENT_FLAG       0x40000000  // Set the event flag upon request completion.
#define SD_BUS_REQUEST_PHYS_BUFFER 0x00008000

// request queue
typedef struct _SD_REQUEST_QUEUE {
    LIST_ENTRY      ListHead;           // list head for all bus requests
    ULONG           QueueCount;         // number of entries
}SD_REQUEST_QUEUE, *PSD_REQUEST_QUEUE;

// definition of interrupt callback for SDIO cards
typedef SD_API_STATUS (*PSD_INTERRUPT_CALLBACK) (SD_DEVICE_HANDLE,   // device handle
                                                 PVOID);             // device context

// typedef for fast-path slot event callback
typedef VOID (*PSD_SLOT_EVENT_CALLBACK) (SD_DEVICE_HANDLE,           // handle
                                         PVOID,                      // device context
                                         SD_SLOT_EVENT_TYPE,         // slot event type
                                         PVOID,                      // slot event data (optional)
                                         DWORD);                     // slot event data size (optional