sdcardddk.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

// 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 <SDMem.h>
#include "SDCard.h"

#define SD_CSD_VERSION_CODE_SUPPORTED   0 // version 1.0
#define MMC_CSD_VERSION_CODE_SUPPORTED  2 // version 3.1

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;

// 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_TYPE_COUNT              // number of SD_INFO_TYPEs
} 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
    Device_HSMMC = 5
}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_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 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;

// 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
} SD_RESPONSE_TYPE, *PSD_RESPONSE_TYPE;

// fast path event callback event types
typedef enum _SD_SLOT_EVENT_TYPE {
    SDCardEjected = 1,         // card ejected
}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;

// 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       CurrentPermissions; // current permissions
} 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 

// 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)

// 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

// bit fields for client registration flags    
#define SD_CLIENT_HANDLES_RETRY 0x00000001         // client driver handles retries

// client registration structure
typedef struct _SDCARD_CLIENT_REGISTRATION_INFO {
    TCHAR                       ClientName[MAX_SDCARD_CLIENT_NAME]; // client name
    PSD_SLOT_EVENT_CALLBACK     pSlotEventCallBack;                 // slot event callback
    DWORD                       ClientFlags;                        // flags
    DWORD                       Reserved1;                          // future use
    DWORD                       Reserved2;                          // future use        
}SDCARD_CLIENT_REGISTRATION_INFO, *PSDCARD_CLIENT_REGISTRATION_INFO;

// parsed CID structure
typedef struct _SD_PARSED_REGISTER_CID{
    UCHAR  ManufacturerID;              // 8 bit manufacturer ID
    CHAR   OEMApplicationID[3];         // 2 character ASCII string NULL terminated
    CHAR   ProductName[7];              // product name string 6 (to accomodate MMC cards) ASCII chars + 1 nul char
    UCHAR  MajorProductRevision;        // 4 bit major
    UCHAR  MinorProductRevision;        // 4 bit minor rev
    DWORD  ProductSerialNumber;         // 32 bit product serial number
    UCHAR  ManufacturingMonth;          // Month, 1=Jan, 12=Dec
    USHORT ManufacturingYear;           // Decoded year, range 2000 upwards
    UCHAR  RawCIDRegister[16];          // raw data
} SD_PARSED_REGISTER_CID, *PSD_PARSED_REGISTER_CID;

// file System type present on card
typedef enum {
    SD_FS_FAT_PARTITION_TABLE,
    SD_FS_FAT_NO_PARTITION_TABLE,
    SD_FS_UNIVERSAL,
    SD_FS_OTHER
} SD_FS_TYPE, *PSD_FS_TYPE;

// parsed CSD structure
typedef struct _SD_PARSED_REGISTER_CSD {
    UCHAR CSDVersion;               // 4 bit CSD version
    struct {
        DOUBLE TAAC;                // The TAAC field in units of nano-seconds
        USHORT NSAC;                // The NSAC field in units of clock-cycle 
    } DataAccessTime;
    ULONG MaxDataTransferRate;      // In units of kbit/s
    USHORT CardCommandClasses;      // 12 bit command class support indicators
    USHORT MaxReadBlockLength;      // In units of bytes
    BOOLEAN ReadBlockPartial;       // Partial Block Read allowed ?
    BOOLEAN WriteBlockMisalign;     // Misaligned Block Writes allowed ?
    BOOLEAN ReadBlockMisalign;      // Misaligned Block Reads allowed ?
    BOOLEAN DSRImplemented;         // DSR Register implemented ?
    ULONG DeviceSize;               // Calculated device memory size in bytes
    USHORT VDDReadCurrentMin;       // in units of milliamps
    USHORT VDDReadCurrentMax;       // in units of milliamps
    USHORT VDDWriteCurrentMin;      // in units of milliamps
    USHORT VDDWriteCurrentMax;      // in units of milliamps
    BOOLEAN EraseBlockEnable;       // Erase in multiples of MaxWriteBlockLength ?
    UCHAR EraseSectorSize;          // Size of an erase sector in blocks (SECTOR_SIZE+1)
    UCHAR WPGroupSize;              // Size of a WP group in erase sectors (WP_GRP_SIZE+1)
    UCHAR WPGroupEnable;            // Group Write Protection possible ?
    UCHAR WriteSpeedFactor;         // Block Write time as multiple of Read access time
    USHORT MaxWriteBlockLength;     // In units of bytes
    BOOLEAN WriteBlockPartial;      // Partial block writes allowed ?
    BOOLEAN CopyFlag;               // Copy control flag
    BOOLEAN PermanentWP;            // Permanent Write Protect flag
    BOOLEAN TemporaryWP;            // Temporary Write Protect flag
    SD_FS_TYPE FileSystem;          // File System type
    UCHAR RawCSDRegister[16];       // raw data
} SD_PARSED_REGISTER_CSD, *PSD_PARSED_REGISTER_CSD;


#include <pshpack1.h>
typedef struct _SD_REGISTER_SCR {
    DWORD ReservedForManufacturer:32;
    WORD  Reserverd:16;
    BYTE  SD_BUS_WIDTHS:4;
    BYTE  SD_SECURITY:3;
    BYTE  DATA_STAT_AFTER_ERASE:1;
    BYTE  SD_SPEC:4;
    BYTE  SCR_STRUCTURE:4;
} SD_REGISTER_SCR, *PSD_REGISTER_SCR;
#include <poppack.h>


typedef USHORT SD_CARD_RCA;         // card RCA
typedef DWORD  SD_CARD_STATUS;      // card status

// DDK api status codes
#define SD_API_STATUS_SUCCESS                          ((SD_API_STATUS)0x00000000L)
#define SD_API_STATUS_PENDING                          ((SD_API_STATUS)0x00000001L)
#define SD_API_STATUS_BUFFER_OVERFLOW                  ((SD_API_STATUS)0xC0000001L)
#define SD_API_STATUS_DEVICE_BUSY                      ((SD_API_STATUS)0xC0000002L)
#define SD_API_STATUS_UNSUCCESSFUL                     ((SD_API_STATUS)0xC0000003L)
#define SD_API_STATUS_NOT_IMPLEMENTED                  ((SD_API_STATUS)0xC0000004L)
#define SD_API_STATUS_ACCESS_VIOLATION                 ((SD_API_STATUS)0xC0000005L)
#define SD_API_STATUS_INVALID_HANDLE                   ((SD_API_STATUS)0xC0000006L)
#define SD_API_STATUS_INVALID_PARAMETER                ((SD_API_STATUS)0xC0000007L)
#define SD_API_STATUS_NO_SUCH_DEVICE                   ((SD_API_STATUS)0xC0000008L)
#define SD_API_STATUS_INVALID_DEVICE_REQUEST           ((SD_API_STATUS)0xC0000009L)
#define SD_API_STATUS_NO_MEMORY                        ((SD_API_STATUS)0xC000000AL)
#define SD_API_STATUS_BUS_DRIVER_NOT_READY             ((SD_API_STATUS)0xC000000BL)
#define SD_API_STATUS_DATA_ERROR                       ((SD_API_STATUS)0xC000000CL)
#define SD_API_STATUS_CRC_ERROR                        ((SD_API_STATUS)0xC000000DL)
#define SD_API_STATUS_INSUFFICIENT_RESOURCES           ((SD_API_STATUS)0xC000000EL)
#define SD_API_STATUS_DEVICE_NOT_CONNECTED             ((SD_API_STATUS)0xC0000010L)
#define SD_API_STATUS_DEVICE_REMOVED                   ((SD_API_STATUS)0xC0000011L)
#define SD_API_STATUS_DEVICE_NOT_RESPONDING            ((SD_API_STATUS)0xC0000012L)
#define SD_API_STATUS_CANCELED                         ((SD_API_STATUS)0xC0000013L)
#define SD_API_STATUS_RESPONSE_TIMEOUT                 ((SD_API_STATUS)0xC0000014L)
#define SD_API_STATUS_DATA_TIMEOUT                     ((SD_API_STATUS)0xC0000015L)
#define SD_API_STATUS_DEVICE_RESPONSE_ERROR            ((SD_API_STATUS)0xC0000016L)
#define SD_API_STATUS_DEVICE_UNSUPPORTED               ((SD_API_STATUS)0xC0000017L)
#define SD_API_STATUS_SHUT_DOWN                        ((SD_API_STATUS)0xC0000018L)

// macro to test for success
#define SD_API_SUCCESS(Status) ((SD_API_STATUS)(Status) >= 0)

// macro to test for success where a SD_API_STATUS_TIMEOUT is okay
#define SD_API_SUCCESS_RESPONSE_TIMEOUT_OK(Status) (((SD_API_STATUS)(Status) >= 0) || (SD_API_STATUS_RESPONSE_TIMEOUT == (SD_API_STATUS)(Status)))

// macro to test explicitly for time out 
#define SD_API_RESPONSE_TIMEOUT(Status) (SD_API_STATUS_RESPONSE_TIMEOUT == (SD_API_STATUS)(Status))

// debug zone slot IDs - user assignable slots
#define SDCARD_ZONESLOT_0             0
#define SDCARD_ZONESLOT_1             1
#define SDCARD_ZONESLOT_2             2
#define SDCARD_ZONESLOT_3             3
#define SDCARD_ZONESLOT_4             4
#define SDCARD_ZONESLOT_5             5
#define SDCARD_ZONESLOT_6             6