mc_api.h

MMI层OBJ不能完全编译

/**
 * @file  mc_api.h
 *
 * API Definition for MC SWE.
 *
 * @author   ()
 * @version 0.1
 */

/*
 * History:
 *
 *  Date        Author          Modification
 *  -------------------------------------------------------------------
 *  7/1/2003   ()   Create.
 *  9/17/2003  ()   API function headers added.
 *
 * (C) Copyright 2003 by ICT Embedded B.V., All Rights Reserved
 */

#ifndef __MC_API_H_
#define __MC_API_H_


#include "rvm/rvm_gen.h"    /* Generic RVM types and functions. */


#ifdef __cplusplus
extern "C"
{
#endif


/*@}*/

/** event typedef */
typedef UINT16 T_MC_EVENTS;

/** Possible events*/
#define MC_EVENT_INSERTION   (0x01)
#define MC_EVENT_REMOVAL    (0x02)


/** used host controller frequency */
#define MC_CLK_SPEED     (1300000)


/** Memory Card type */
typedef enum {
    NO_CARD,
    SD_CARD,
    MMC_CARD
} T_MC_CARD_TYPE;

/** Mechanical write protection type of a SD card*/
typedef enum {
    NO_SD_CARD,
    PROTECTED,
    NOT_PROTECTED
} T_MC_SD_MECH_WP;

typedef UINT16 T_MC_RCA;

typedef UINT16 T_MC_SUBSCRIBER;

typedef enum {
    MC_RW_STREAM,
    MC_RW_BLOCK
} T_MC_RW_MODE;

typedef enum {
    CSD_ACTION_WRITE,
    CSD_ACTION_ERASE
} T_MC_CSD_ACTION;

/* Indicates whether to use DMA or let the CPU handle the copying. Possible 
 * values 
 */
typedef enum {
    MC_FORCE_CPU,  /* Use CPU to transfer MC-data to RAM */
    MC_FORCE_DMA,  /* Use DMA to transfer MC-data to RAM */
    MC_DMA_AUTO    /* Driver determines CPU or DMA transfer */
} T_MC_DMA_MODE;

typedef enum {
    CSD_FIELD_FILE_FORMAT_GRP,
    CSD_FIELD_COPY,
    CSD_FIELD_PERM_WRITE_PROTECT,
    CSD_FIELD_TMP_WRITE_PROTECT,
    CSD_FIELD_FILE_FORMAT,
    CSD_FIELD_FILE_ECC,
    CSD_FIELD_FILE_CRC
} T_MC_CSD_FIELD;



/**
 * @name API functions
 *
 * API functions declarations (bridge functions).
 */
/*@{*/

/**
 * Subscribe
 *
 * Detailled description.
 * This functions shall be used by a client to subscribe to the MC-driver. 
 * After registration the client is able to use the driver services like 
 * reading and writing data.
 *
 * @param   subscriber_p  Subscriber identification value, which shall be 
 *                        allocated by the client and is filled by the driver.
 *          return_path   The return path of the client.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory. Client could not be subscribed 
 *                        because maximum number of clients have been reached.
 */                 
extern T_RV_RET mc_subscribe (T_MC_SUBSCRIBER *subscriber_p, 
                               T_RV_RETURN return_path);

/**
 * Unsubscribe
 *
 * Detailled description.
 * This function shall be used by a client to unsubscribe from the driver. 
 * After calling this function the client will no longer able to use the 
 * driver services.
 *
 * @param   subscriber_p  Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_INVALID_PARAMETER The subscriber id is invalid.
 */
extern T_RV_RET mc_unsubscribe (T_MC_SUBSCRIBER *subscriber_p);

/**
 * Read
 *
 * Detailled description.
 * This function reads data from a MC-card using a specific transfer mode. 
 * If partial reads are allowed (if CSD parameter READ_BL_PARTIAL is set) the 
 * start address can start and stop at any address within the card address 
 * space, otherwise it shall start and stop at block boundaries. The client 
 * is responsible for setting the correct mode, address and data size 
 * parameter according to the device properties. The client can obtain these 
 * properties by reading the CSD-register.
 *
 * @param   rca           Relative Card Address.
 *          mode          The data transfer mode to use. The MC-specification 
 *                        defines stream oriented data transfer and block 
 *                        oriented data transfer. Only stream mode is supported 
 *                        at this moment.
 *          addr          The physical start address in bytes units from where 
 *                        to read data.
 *          data_p        Pointer to a destination buffer, provided by the 
 *                        client, where the driver will put the data. The 
 *                        buffer size shall be at least data_size bytes.
 *          data_size     Number of bytes to be read from the card.
 *          subscriber    Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory
 */
extern T_RV_RET mc_read (T_MC_RCA rca, T_MC_RW_MODE mode, UINT32 addr,
                          UINT8 *data_p, UINT32 data_size,
                          T_MC_SUBSCRIBER subscriber);

/**
 * Write
 *
 * Detailled description.
 * This function writes data to a MC-card using a specific transfer mode. If 
 * partial reads are allowed (if CSD parameter READ_BL_PARTIAL is set) the 
 * start address can start and stop at any address within the card address 
 * space, otherwise it shall start and stop at block boundaries. The client 
 * is responsible for setting the correct mode, address and data size parameter 
 * according to the device properties. The client can obtain these properties 
 * by reading the CSD-register.
 *
 * @param   rca           Relative Card Address.
 *          mode          The data transfer mode to use. The MC-specification 
 *                        defines stream oriented data transfer and block 
 *                        oriented data transfer. Only stream mode is supported 
 *                        at this moment.
 *          addr          The physical start address in bytes units from where 
 *                        to write data.
 *          data_p        Pointer to a source buffer, provided by the client, 
 *                        from where the driver will read the data. The buffer
 *                        size shall be at least data_size bytes.
 *          data_size     Number of bytes to be written to the card.
 *          subscriber    Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory
 */
extern T_RV_RET mc_write (T_MC_RCA rca, T_MC_RW_MODE mode, UINT32 addr,
                           UINT8 *data_p, UINT32 data_size,
                           T_MC_SUBSCRIBER subscriber);

/**
 * Erase
 *
 * Detailled description.
 * This function erases a range of erase groups on the card. The size of the
 * erase group is specified in the CSD. The erase group start and end address 
 * is given in bytes units. This address will be rounded to down to the erase 
 * group boundary.
 *
 * @param   rca           Relative Card Address.
 *          start_group   Erase group address in bytes units where erasing will
 *                        start.
 *          end_group     Erase group address in bytes units where erasing will 
 *                        end.
 *          subscriber    Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory
 */
extern T_RV_RET mc_erase (T_MC_RCA rca, UINT32 erase_group_start,
                           UINT32 erase_group_end, 
                           T_MC_SUBSCRIBER subscriber);

/**
 * Set write protect
 *
 * Detailled description.
 * This function sets the write protection of the addressed write protect 
 * group against erase or write. The group size is defined in units of 
 * WP_GRP_SIZE erase group as specified in the CSD. This function does not 
 * write protect the entire card which can be done by setting the permanent or
 * temporary write protect bits in the CSD. For this the mc_write_CSD() 
 * function shall be used.
 *
 * @param   rca           Relative Card Address.
 *          wr_prot_group The group address in byte units. The LSB抯 below 
 *                        the group size will be ignored.
 *          subscriber    Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory
 */
extern T_RV_RET mc_set_write_protect (T_MC_RCA rca, UINT32 wr_prot_group,
                                       T_MC_SUBSCRIBER subscriber);

/**
 * Clear write protect
 *
 * Detailled description.
 * This function clears the write protection of the addressed write protect 
 * group. The group size is defined in units of WP_GRP_SIZE erase group as 
 * specified in the CSD. This function does not disable write protect of the 
 * entire card which can be done by erasing the temporary write protect bits 
 * in the CSD. For this the mc_write_CSD() function shall be used.
 *
 * @param   rca           Relative Card Address.
 *          wr_prot_group The group address in byte units. The LSB抯 below 
 *                        the group size will be ignored.
 *          subscriber    Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory
 */
extern T_RV_RET mc_clr_write_protect (T_MC_RCA rca, UINT32 wr_prot_group,
                                       T_MC_SUBSCRIBER subscriber);

/**
 * return the mechanical write protection
 *
 * This function will return the mechanical write protection of
 * a SD-card.
 *
 * @param   rca         RCA of card
 *
 * @return  NO_SD_CARD
 *          PROTECTED
 *          NOT_PROTECTED
 */

/*@{*/
T_MC_SD_MECH_WP mc_sd_get_mech_wp(T_MC_RCA rca);

/**
 * Get write protect
 *
 * Detailled description.
 * This function reads 32 write protection bits representing 32 write protect
 * groups starting at the specified address.
 *
 * @param   rca           Relative Card Address.
 *          wr_prot_group The group address in byte units. The LSB抯 below 
 *                        the group size will be ignored.
 *          subscriber    Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory
 */
extern T_RV_RET mc_get_write_protect (T_MC_RCA rca, UINT32 wr_prot_group,
                                       T_MC_SUBSCRIBER subscriber);

/**
 * Get card status
 *
 * Detailled description.
 * This function returns the 32-bit status register of the MC-card. This 
 * status is not buffered in the driver but will be read directly from 
 * the card. See [MC], paragraph 4.10 for an explanation of the status bits.
 *
 * @param   rca           Relative Card Address.
 *          subscriber    Subscriber identification value.
 * @return  RV_OK         Success
 *          RV_NOT_READY  The driver is not able to handle this request at 
 *                        this moment.
 *          RV_MEMORY_ERR Insufficient memory
 */
extern T_RV_RET mc_get_card_status(T_MC_RCA rca,
                                    T_MC_SUBSCRIBER subscriber);

/**
 * Get controller status
 *
 * Detailled description.
 * This function returns 16-bit MC- host controller status register 
 * [MC_STAT].
 *
 * @param   status        Pointer to status register allocated by client and