mu_mtpcsi.h

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

/******************************************************************
*                                                                *
*        Copyright Mentor Graphics Corporation 2005              *
*                                                                *
*                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.                    *
*                                                                *
******************************************************************/

/*
 * MUSBStack-S MTP Protocol/Command-Set Interface (MTPCSI)
 * $Revision: 1.1 $
 */

#ifndef __MUSB_MTP_MTPCSI_H__
#define __MUSB_MTP_MTPCSI_H__

#include "mu_cdi.h"
#include "mu_gmtp.h"


/************************************************************/
/****************        MTP          ***********************/
/************************************************************
 * MTP Protocol/Command-Set Interface (MTPCSI) introduction.
 * This is the interface between the protocol (also called "transport")
 * and the command-set implementations.
 * In USB MTP devices, the protocol is given in the bInterfaceProtocol
 * field, and the command-set is given in the bInterfaceSubclass field.
 */

/**
 * Command-complete callback.
 * Callback for command completion
 * @param pPrivateData private data
 * @param pDataBuffer associated data
 * @param dwDataLength length of data
 * @param bUsbError TRUE if a USB error occurred while obtaining
 * the data and/or status (STALL, NAK limit, packet too short)
 * @param pStatusBuffer buffer of status (CB/CBI only)
 * @param wStatusLength length of status buffer
 */
typedef void (*MGC_pfMtpProtocolCmdComplete)(void* pPrivateData,
					                const uint8_t* pDataBuffer,
					                     uint32_t  dwDataLength,
					                     uint16_t  bUsbError,
					                const uint8_t* pStatusBuffer,
					                     uint16_t  wStatusLength);

/**
 * Start a MTP device.
 * Implementations should perform any protocol-specific device initialization,
 * and eventually call the command-set's discovery function.
 * @param pProtocolData protocol handler instance data
 * @param pDevice UCDI device to start
 * @return TRUE on success
 * @return FALSE on failure
 * @see #MGC_pfMtpCmdSetDiscoverDevice
 */
typedef uint8_t (*MGC_pfMtpProtocolStartDevice)(void* pProtocolData,	MUSB_Device* pDevice);

/**
 * Send a MTP command.
 * Using the appropriate transport, send a command to the device
 * and call the callback when data and status is received.
 * @param pProtocolData protocol handler instance data
 * @param pPrivateData caller private data; passed in completion callback
 * @param bNumberOfParam Number of parameter (max 5)
 * @param ParamN a pointer of param-N
 * @param pCmd a buffer containing the command
 * @param bCmdLength the length of the command buffer
 * @param pDataBuffer data buffer
 * @param dwDataLength the length of data to send or max expected to recv
 * @param bSend TRUE to send data; FALSE to receive
 * @param pfCmdComplete completion callback
 * @param bAllowDma TRUE to allow DMA; FALSE otherwise
 * @return TRUE on successful queueing of the command
 * @return FALSE on failure
 */
typedef uint8_t (*MGC_pfMtpProtocolSendCmd)(void*    pProtocolData, 
				                            void*    pPrivateData,
				                           uint8_t   bNumberOfParam,
				                    const uint32_t*  ParamN, 
				                           uint16_t  pCmd, 
				                           uint8_t*  pDataBuffer,
				                           uint32_t  dwDataLength,
				                           uint8_t   bSend, 
				       MGC_pfMtpProtocolCmdComplete  pfCmdComplete,
				                           uint8_t   bAllowDma);

/**
 * Set device information.
 * The implementation will set the fields required from the USB device
 * (vendor/device ID, product version, bus address).
 * @param pProtocolData protocol handler instance data
 * @param pInfo pointer to device information; callee makes a copy
 */
typedef uint8_t (*MGC_pfMtpProtocolSetDeviceInfo)(void* pProtocolData,
						      const MUSB_GmtpDeviceInfo* pInfo);

/**
 * MGC_MtpProtocol.
 * A MTP protocol implementation.
 */
typedef struct
{
	void* pProtocolData;
	MGC_pfMtpProtocolStartDevice	pfStartDevice;
	MGC_pfMtpProtocolSendCmd		pfSendCmd;
	MGC_pfMtpProtocolSetDeviceInfo	pfSetDeviceInfo;
} MGC_MtpProtocol;


/**
 * Command-set-specific read command generation.
 * Fill the given buffer with a command suitable to perform
 * a read under the given conditions.
 * @return command length (the relevant portion of the command buffer)
 */
typedef uint8_t (*MGC_pfMtpCmdSetSendCmd)(uint8_t bLun);

/**
 * Create a new command-set instance
 * @param bLunCount number of LUNs in device
 */
typedef void* (*MGC_pfMtpCmdSetCreateInstance)(uint8_t bLunCount);

/**
 * Destroy a command-set instance
 */
typedef void (*MGC_pfMtpCmdSetDestroyInstance)(void* pInstance);

/**
 * MGC_MtpCmdSet.
 * A MTP command set.
 * This allows the transport layer to use any supported command set
 */
typedef struct
{
	MGC_pfMtpCmdSetCreateInstance	pfCreateInstance;
	MGC_pfMtpCmdSetDestroyInstance	pfDestroyInstance;
	MGC_pfMtpCmdSetSendCmd			pfSendCmd;
} MGC_MtpCmdSet;

#endif	/* multiple inclusion protection */