mu_hfi.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 HFI (Host Filesystem Interface).
 * $Revision: 1.4 $
 */

#ifndef __MUSB_HFI_H__
#define __MUSB_HFI_H__

#include "mu_tools.h"

/** 
 * Introduction to Host Filesystem Interface.
 * The functions herein can be implemented by an OS to allow
 * the Mentor USB mass-storage 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 mass-storage 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 HFI implementation).  This eases its use in a non-OS environment,
 * and allows flexible and optimal HFI implementation for each OS.
 */

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

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

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

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

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

/** 
 * MUSB_HfiMediaType.
 * HFI Media Type.
 */
typedef enum
{
    /** Unknown media type */
    MUSB_HFI_MEDIA_UNKNOWN,
    /** Fixed media */
    MUSB_HFI_MEDIA_FIXED,
    /** Removable media */
    MUSB_HFI_MEDIA_REMOVABLE
} MUSB_HfiMediaType;

/** 
 * MUSB_HfiAccessType.
 * HFI Access Type.
 */
typedef enum
{
    /** Random access read/write (e.g. hard disk, flash, floppy) */
    MUSB_HFI_ACCESS_RANDOM,
    /** Random access write-once (e.g. recordable CD/DVD) */
    MUSB_HFI_ACCESS_RANDOM_WRITE_ONCE,
    /** Random access read-only (e.g. CD/DVD) */
    MUSB_HFI_ACCESS_RANDOM_READ
} MUSB_HfiAccessType;

/** 
 * MUSB_HfiStatus.
 * HFI Operation Status.
 */
typedef enum
{
    /** success */
    MUSB_HFI_SUCCESS,
    /** error: unsupported block size (try another if possible) */
    MUSB_HFI_ERROR_UNSUPPORTED_BLOCKSIZE,
    /** error: media is currently write-protected */
    MUSB_HFI_ERROR_MEDIA_PROTECTED,
    /** error: media was removed before operation could complete */
    MUSB_HFI_ERROR_MEDIA_REMOVED,
    /** error: device was removed before operation could complete */
    MUSB_HFI_ERROR_DEVICE_REMOVED,
    /** error: transfer to/from media failed */
    MUSB_HFI_ERROR_TRANSFER,
    /** error: data verify failed */
    MUSB_HFI_ERROR_VERIFY,
    /** error: device busy */
    MUSB_HFI_ERROR_BUSY,
    /** error: out of memory */
    MUSB_HFI_NO_MEMORY
} MUSB_HfiStatus;

/*************************** HFI TYPES ****************************/

/**
 * MUSB_HfiMediumInfo.
 * Storage medium information.
 * @field AccessType the medium's access type
 * @field dwBlockSize the fundamental medium block size, in bytes
 * @field dwBlockCountLo lower 32 bits of block count
 * @field dwBlockCountHi upper 32 bits of block count
 * @field awSerialNumber medium serial number string, 
 * up to MUSB_HFI_MAX_VOLUME_SERIAL UNICODE characters,
 * terminated by wide-NUL
 */
typedef struct
{
    MUSB_HfiAccessType AccessType;
    uint32_t dwBlockSize;
    uint32_t dwBlockCountLo;
    uint32_t dwBlockCountHi;
    uint16_t awSerialNumber[MUSB_HFI_MAX_VOLUME_SERIAL+1];
} MUSB_HfiMediumInfo;
 
/**
 * MUSB_HfiDeviceInfo.
 * Device information.
 * A mass-storage device driver fills this with any information
 * it knows before calling MUSB_HfiAddDevice.
 * 
 * @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_HfiAccessType 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_HFI_MAX_VOLUME_SERIAL UNICODE characters,
 * terminated by wide-NUL
 * 
 * @field wVendorId USB VID,
 * for the HFI implementation's use in generating a volume name
 * 
 * @field wProductId USB PID,
 * for the HFI implementation's use in generating a volume name
 * 
 * @field bcdDevice USB bcdDevice,
 * for the HFI implementation's use in generating a volume name
 * 
 * @field bBusAddress USB device address, 
 * for the HFI implementation's use in generating a volume name
 * 
 * @field awDiskVendor vendor string for the underlying disk, 
 * up to MUSB_HFI_MAX_DISK_VENDOR UNICODE characters,
 * terminated by wide-NUL
 * 
 * @field awDiskProduct product string for the underlying disk, 
 * up to MUSB_HFI_MAX_DISK_PRODUCT UNICODE characters,
 * terminated by wide-NUL
 * 
 * @field awDiskVendor revision string for the underlying disk, 
 * up to MUSB_HFI_MAX_DISK_REVISION UNICODE characters,
 * terminated by wide-NUL
 * 
 */
typedef struct
{
    MUSB_HfiMediaType MediaType;
    MUSB_HfiMediumInfo InitialMedium;
    uint16_t bmAccessType;
    uint8_t bCanFormat;
    uint8_t bHasCache;
    uint32_t dwBlockSize;
    uint16_t awSerialNumber[MUSB_HFI_MAX_VOLUME_SERIAL+1];
    uint16_t wVendorId;
    uint16_t wProductId;
    uint16_t bcdDevice;
    uint8_t bBusAddress;
    uint8_t bPad[3];
    uint16_t awDiskVendor[MUSB_HFI_MAX_DISK_VENDOR+1];
    uint16_t awDiskProduct[MUSB_HFI_MAX_DISK_PRODUCT+1];
    uint16_t awDiskRevision[MUSB_HFI_MAX_DISK_REVISION+1];
    uint8_t bLunCount;	//[LL]
    uint8_t bPad2[3];		//[LL]
} MUSB_HfiDeviceInfo;

/** Handle created by the HFI implementation */
typedef void* MUSB_HfiVolumeHandle;

/**
 * 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_HfiAddDevice
 * @param bSuccess TRUE on success; FALSE on failure
 */
typedef void (*MUSB_pfHfiMountComplete)(MUSB_HfiVolumeHandle hVolume, 
					uint8_t bSuccess);

/**
 * Transfer completion callback.
 * Read and write are asynchronous requests, so the HFI implementation
 * supplies this callback to be notified on their completion.
 * @param hVolume a volume handle as filled by a successful MUSB_HfiAddDevice
 * @param wActualBlocks the actual number of blocks successfully read
 * or written(/verified)
 */
typedef void (*MUSB_pfHfiTransferComplete)(MUSB_HfiVolumeHandle hVolume,
uint16_t wActualBlocks);

/**
 * Medium-check completion callback.