mu_gmtp.h

本程序为ST公司开发的源代码

/******************************************************************
 *                                                                *
 *        Copyright Mentor Graphics Corporation 2006              *
 *                                                                *
 *                All Rights Reserved.                            *
 *                                                                *
 *    THIS WORK CONTAINS TRADE SECRET AND PROPRIETARY INFORMATION *
 *  WHICH IS THE PROPERTY OF MENTOR GRAPHICS CORPORATION OR ITS   *
 *  LICENSORS AND IS SUBJECT TO LICENSE TERMS.                    *
 *                                                                *
 ******************************************************************/

/*
 * MUSB-MicroSW GMTP (Generic MTP Interface).
 * $Revision: 1.1 $
 */

#ifndef __MUSB_GMTP_H__
#define __MUSB_GMTP_H__

#include "mu_tools.h"

/** 
 * Introduction to Generic MTP Interface.
 * The functions herein can be implemented by an OS to allow
 * the Mentor USB media transfer protocol (MTP) driver to be hooked into the OS'
 * filesystem mechanisms, thus allowing the Mentor driver to be
 * used without additional effort.
 * The callbacks herein are implemented by the Mentor driver,
 * exposing the functionality needed by an OS to use the MTP device.
 * The above could also be applied to a custom, non-OS environment.
 * The driver is threadless (it reacts to callbacks from the BSR context
 * and the GMTP implementation).  This eases its use in a non-OS environment,
 * and allows flexible and optimal GMTP implementation for each OS.
 */

/************************* HFI CONSTANTS **************************/

/** Maximum number of UNICODE characters supported for serial number */
#define MUSB_GMTP_MAX_VOLUME_SERIAL	31

/** Maximum number of UNICODE characters supported for disk vendor ID */
#define MUSB_GMTP_MAX_DISK_VENDOR	15

/** Maximum number of UNICODE characters supported for disk product ID */
#define MUSB_GMTP_MAX_DISK_PRODUCT	31

/** Maximum number of UNICODE characters supported for disk revision ID */
#define MUSB_GMTP_MAX_DISK_REVISION	7

/** 
 * MUSB_GmtpMediaType.
 * GMTP Media Type.
 */
typedef enum
{
    /** Unknown media type */
    MUSB_GMTP_MEDIA_UNKNOWN,
    /** Fixed media */
    MUSB_GMTP_MEDIA_FIXED,
    /** Removable media */
    MUSB_GMTP_MEDIA_REMOVABLE
} MUSB_GmtpMediaType;

/** 
 * MUSB_GmtpAccessType.
 * GMTP Access Type.
 */
typedef enum
{
    /** Random access read/write (e.g. hard disk, flash, floppy) */
    MUSB_GMTP_ACCESS_RANDOM,
    /** Random access write-once (e.g. recordable CD/DVD) */
    MUSB_GMTP_ACCESS_RANDOM_WRITE_ONCE,
    /** Random access read-only (e.g. CD/DVD) */
    MUSB_GMTP_ACCESS_RANDOM_READ
} MUSB_GmtpAccessType;

/** 
 * MUSB_GmtpStatus.
 * GMTP Operation Status.
 */
typedef enum
{
    /** success */
    MUSB_GMTP_SUCCESS,
    /** error: media was removed before operation could complete */
    MUSB_GMTP_ERROR_MEDIA_REMOVED,
    /** error: transfer to/from media failed */
    MUSB_GMTP_ERROR_TRANSFER,
    /** error: data verify failed */
    MUSB_GMTP_ERROR_VERIFY
} MUSB_GmtpStatus;

/*************************** GMTP TYPES ****************************/

/**
 * MUSB_GmtpDeviceInfo.
 * Device information.
 * A MTP device driver fills this with any information.
 * 
 * @field MediaType media type
 * 
 * @field InitialMedium medium present at call time, if any
 * (for fixed-media devices, this is the permanent medium)
 * 
 * @field bmAccessType bitmask representing possible access types
 * (1's shifted left by the MUSB_GmtpAccessType values).
 * A fixed-media device should have just one,
 * while removable-media devices may support multiple types.
 * 
 * @field bCanFormat TRUE if device can be (low-level) formatted
 * 
 * @field bHasCache TRUE if device has a built-in cache,
 * so a flush may be required before removal for data integrity
 * 
 * @field bSequential TRUE if device access is fundamentally sequential,
 * i.e. a tape drive
 * 
 * @field dwBlockSize the fundamental device block size, in bytes
 * 
 * @field awSerialNumber device serial number string, 
 * up to MUSB_GMTP_MAX_VOLUME_SERIAL UNICODE characters,
 * terminated by wide-NUL
 * 
 * @field wVendorId USB VID,
 * for the GMTP implementation's use in generating a volume name
 * 
 * @field wProductId USB PID,
 * for the GMTP implementation's use in generating a volume name
 * 
 * @field bcdDevice USB bcdDevice,
 * for the GMTP implementation's use in generating a volume name
 * 
 * @field bBusAddress USB device address, 
 * for the GMTP implementation's use in generating a volume name
 * 
 * @field awDiskVendor vendor string for the underlying disk, 
 * up to MUSB_GMTP_MAX_DISK_VENDOR UNICODE characters,
 * terminated by wide-NUL
 * 
 * @field awDiskProduct product string for the underlying disk, 
 * up to MUSB_GMTP_MAX_DISK_PRODUCT UNICODE characters,
 * terminated by wide-NUL
 * 
 * @field awDiskVendor revision string for the underlying disk, 
 * up to MUSB_GMTP_MAX_DISK_REVISION UNICODE characters,
 * terminated by wide-NUL
 * 
 */
typedef struct
{
    MUSB_GmtpMediaType MediaType;
    uint16_t bmAccessType;
    uint8_t bCanFormat;
    uint8_t bHasCache;
    uint32_t dwBlockSize;
    uint16_t awSerialNumber[MUSB_GMTP_MAX_VOLUME_SERIAL+1];
    uint16_t wVendorId;
    uint16_t wProductId;
    uint16_t bcdDevice;
    uint8_t bBusAddress;
    uint8_t bPad[3];
    uint16_t awDiskVendor[MUSB_GMTP_MAX_DISK_VENDOR+1];
    uint16_t awDiskProduct[MUSB_GMTP_MAX_DISK_PRODUCT+1];
    uint16_t awDiskRevision[MUSB_GMTP_MAX_DISK_REVISION+1];
} MUSB_GmtpDeviceInfo;

/** Handle created by the GMTP implementation */
typedef void* MUSB_GmtpVolumeHandle;

/**
 * Mount completion callback.
 * Mount is an asynchronous request, so the HFI implementation
 * supplies this callback to be notified on its completion.
 * @param hVolume a volume handle as filled by a successful MUSB_GmtpAddDevice
 * @param bSuccess TRUE on success; FALSE on failure
 */
typedef void (*MUSB_pfGmtpMountComplete)(MUSB_GmtpVolumeHandle hVolume, 
					uint8_t bSuccess);

/**
 * Transfer completion callback.
 * Read and write are asynchronous requests, so the GMTP implementation
 * supplies this callback to be notified on their completion.
 * @param hVolume a volume handle as filled.
 * @param pRespondParam report of the response parameter from device.
 * @param wMtpError report of the result of MTP transition successfully read
 * or written(/verified)
 */
typedef void (*MUSB_pfGmtpTransferComplete)(MUSB_GmtpVolumeHandle hVolume,
											uint32_t*		pRespondParam,
											uint16_t		wMtpError);

/**
 * Begin a read/write from a MTP device.
 * @param pDeviceData pPrivateData from associated MUSB_GmtpDevice
 * @param bDirection read or write direction
 * @param pOpeCode MTP command code
 * @param bNumberOfParam how many parameter number
 * @param ParamN parameter[0 - 4]
 * @param dwDataLength how many length of read/write data
 * @param pDataBuffer pointer to a buffer of sufficient size
 * to hold dwDataLength in the device
 * @param pfTransferComplete callback for completion
 * @param bAllowDma TRUE to allow DMA; FALSE otherwise
 * @return status code
 */
typedef MUSB_GmtpStatus (*MUSB_pfGmtpMtpReadWriteDevice)(void     *pDeviceData, 
				                                       uint8_t   bDirection,           // read or write
				                                       uint16_t  pOpeCode, 
				                                       uint8_t   bNumberOfParam,
				                                       uint32_t* ParamN, 
					                                   uint32_t  dwDataLength,
					                                   uint8_t   *pDataBuffer, 
					                                   MUSB_pfGmtpTransferComplete pfTransferComplete,
					                                   uint8_t   bAllowDma);

/**
 * MUSB_GmtpDevice.
 * Device driver callbacks (dispatch table).
 * @field pPrivateData device driver private data; 
 * not to be interpreted by the GMTP implementation
 * @field pfMountVolume volume-mount service
 * @field pfGetMediumInfo device medium-info service
 * @field pfReadDevice device read service
 * @field pfWriteDevice device write service
 * @field pfFlushDevice device flush service
 */
typedef struct 
{
    void* pPrivateData;
    MUSB_pfGmtpMtpReadWriteDevice pfMtpReadWriteDevice;
} MUSB_GmtpDevice;

/************************* GMTP FUNCTIONS **************************/

/* Thsi is first call function after completed to find MTP device */
/* Treat device information and report "device found" to Upper layer */
extern void MUSB_GmtpMtpDeviceMounted(const void*           pDataBuffer,
                                     MUSB_GmtpVolumeHandle* phVolume,
                                     MUSB_GmtpDeviceInfo*   pDeviceInfo,
                                     MUSB_GmtpDevice*       pDevice);

/**
 * A MTP device was removed.
 * A MTP device driver calls this to inform the GMTP implementation
 * that the device corresponding to a volume has been removed.
 * @param hVolume a volume handle as filled by a successful MUSB_GmtpAddDevice
 */
extern void MUSB_GmtpDeviceRemoved(MUSB_GmtpVolumeHandle hVolume);

#endif	/* multiple inclusion protection */