/* Cypress West Bridge API header file (cyasmisc.h)

 ## ===========================

 ##

 ##  Copyright Cypress Semiconductor Corporation, 2006-2009,

 ##  All Rights Reserved

 ##  UNPUBLISHED, LICENSED SOFTWARE.

 ##

 ##  CONFIDENTIAL AND PROPRIETARY INFORMATION

 ##  WHICH IS THE PROPERTY OF CYPRESS.

 ##

 ##  Use of this file is governed

 ##  by the license agreement included in the file

 ##

 ##     <install>/license/license.txt

 ##

 ##  where <install> is the Cypress software

 ##  installation root directory path.

 ##

 ## ===========================

*/

#ifndef _INCLUDED_CYASMISC_H_

#define _INCLUDED_CYASMISC_H_

#include "cyashal.h"

#include "cyastypes.h"

#include "cyasmedia.h"

#include "cyas_cplus_start.h"

#define CY_AS_LEAVE_STANDBY_DELAY_CLOCK		(1)

#define CY_AS_RESET_DELAY_CLOCK			(1)

#define CY_AS_LEAVE_STANDBY_DELAY_CRYSTAL	(5)

#define CY_AS_RESET_DELAY_CRYSTAL		(5)

/* The maximum number of buses supported */

#define	CY_AS_MAX_BUSES				        (2)

/* The maximum number of storage devices supported per bus */

#define	CY_AS_MAX_STORAGE_DEVICES			(1)

#define CY_AS_FUNCTCBTYPE_DATA_MASK (0x60000000U)

#define CY_AS_FUNCTCBTYPE_TYPE_MASK (0x1FFFFFFFU)

#define CyAsFunctCBTypeGetType(t) ((CyAsFunctCBType)((t) & CY_AS_FUNCTCBTYPE_TYPE_MASK))

#define CyAsFunctCBTypeContainsData(t) (((CyAsFunctCBType)((t) & CY_AS_FUNCTCBTYPE_DATA_MASK)) == CY_FUNCT_CB_DATA)

/*****************************************************************************

 * West Bridge Types

 ****************************************************************************/

/* Summary

   Specifies a handle to an West Bridge device

   Description

   This type represents an opaque handle to an West Bridge device.  This handle is

   created via the CyAsMiscCreateDevice() function and is used in all subsequent

   calls that communicate to the West Bridge device.

   See Also

   * CyAsMiscCreateDevice

   * CyAsMiscDestroyDevice

*/

typedef void * CyAsDeviceHandle ;

/* Summary

   This data type gives the mode for the DACK# signal

*/

typedef enum CyAsDeviceDackMode

{

    CyAsDeviceDackAck,		    /* Operate in the ACK mode */

    CyAsDeviceDackEob		    /* Operate in the EOB mode */

} CyAsDeviceDackMode ;

/* Summary

   This data structure gives the options for all hardware features.

   Description

   This structure contains the information required to initialize the West Bridge hardware.

   Any features of the device that can be configured by the caller are specified here.

   See Also

   * CyAsMiscConfigure

*/

typedef struct CyAsDeviceConfig

{

    CyBool                              srammode ;      /* If TRUE, the P port is running in SRAM mode. */

    CyBool				sync ;		/* If TRUE, the P port is synchronous, otherwise async */

    CyBool				dmaintr ;	/* If TRUE, DMA req will be delivered via the interrupt signal */

    CyAsDeviceDackMode			dackmode ;	/* Mode for the DACK# signal */

    CyBool				drqpol ;	/* If TRUE, the DRQ line is active high, otherwise active low */

    CyBool				dackpol ;	/* If TRUE, the DACK line is active high, otherwise active low */

    CyBool				crystal ;	/* If TRUE, the clock is connected to a crystal, otherwise it is

							   connected to a clock */

} CyAsDeviceConfig ;

/* Summary

   Specifies a resource that can be owned by either the West Bridge device or by the processor.

   Description

   This enumerated type identifies a resource that can be owned either by

   the West Bridge device, or by the processor attached to the P port of the

   West Bridge device.

   See Also

   * CyAsMiscAcquireResource

   * CyAsMiscReleaseResource

*/

typedef enum CyAsResourceType

{

    CyAsBusUSB = 0, /* The USB D+ and D- pins */

    CyAsBus_1  = 1, /* The SDIO bus */

    CyAsBus_0  = 2	/* The NAND bus (not implemented) */

} CyAsResourceType;

/* Summary

   Specifies the reset type for a software reset operation.

   Description

   When the West Bridge device is reset, there are two types of reset that are

   possible.  This type indicates the type of reset requested.

   Notes

   Both of these reset types are software based resets; and are distinct from

   a chip level HARD reset that is applied through the reset pin on the West Bridge.

   The CyAsResetSoft type resets only the on-chip micro-controller in the West Bridge.

   In this case, the previously loaded firmware will continue running. However,

   the Storage and USB stack operations will need to be restarted, as any state

   relating to these would have been lost.

   The CyAsResetHard type resets the entire West Bridge chip, and will need a fresh

   configuration and firmware download.  

   See Also

   * <LINK CyAsMiscReset>

 */

typedef enum CyAsResetType

{

    CyAsResetSoft,					/* Just resets the West Bridge micro-controller */

    CyAsResetHard					/* Resets entire device, firmware must be reloaded and

							   the West Bridge device must be re-initialized */

} CyAsResetType;

/* Summary

   This type specifies the polarity of the SD power pin.

   Description

   Sets the SD power pin ( port C, bit 6) to active low or active high.

*/

typedef enum CyAsMiscSignalPolarity

{

    CyAsMiscActiveHigh,

    CyAsMiscActiveLow

} CyAsMiscSignalPolarity ;

/* Summary

   This type specifies the type of the data returned by a Function Callback.

   Description

   CY_FUNCT_CB_NODATA - This callback does not return any additional information in the data field.

   CY_FUNCT_CB_DATA   - The data field is used, and the CyAsFunctCBType will also contain the type of this data.

   See Also

   CyAsFunctionCallback

*/

typedef enum CyAsFunctCBType

{

    CY_FUNCT_CB_INVALID = 0x0U, 

    CY_FUNCT_CB_MISC_GETFIRMWAREVERSION,        /* Data from a CyAsMiscGetFirmwareVersion call. */

    CY_FUNCT_CB_MISC_HEARTBEATCONTROL,          /* Data from a CyAsMiscHeartBeatControl call. */

    CY_FUNCT_CB_MISC_ACQUIRERESOURCE,           /* Data from a CyAsMiscAcquireResource call. */

    CY_FUNCT_CB_MISC_READMCUREGISTER,           /* Data from a CyAsMiscReadMCURegister call. */

    CY_FUNCT_CB_MISC_WRITEMCUREGISTER,          /* Data from a CyAsMiscWriteMCURegister call. */

    CY_FUNCT_CB_MISC_SETTRACELEVEL,             /* Data from a CyAsMiscSetTraceLevel call. */

    CY_FUNCT_CB_MISC_STORAGECHANGED,            /* Data from a CyAsMiscStorageChanged call. */

    CY_FUNCT_CB_MISC_GETGPIOVALUE,              /* Data from a CyAsMiscGetGpioValue call. */

    CY_FUNCT_CB_MISC_SETGPIOVALUE,              /* Data from a CyAsMiscSetGpioValue call. */

    CY_FUNCT_CB_MISC_DOWNLOADFIRMWARE,          /* Data from a CyAsMiscDownloadFirmware call. */

    CY_FUNCT_CB_MISC_ENTERSTANDBY,		/* Data from a CyAsMiscEnterStandby call. */

    CY_FUNCT_CB_MISC_ENTERSUSPEND,              /* Data from a CyAsMiscEnterSuspend call. */

    CY_FUNCT_CB_MISC_LEAVESUSPEND,              /* Data from a CyAsMiscLeaveSuspend call. */

    CY_FUNCT_CB_MISC_RESET,                     /* Data from a CyAsMiscReset call. */

    CY_FUNCT_CB_MISC_SETSDFREQ,                 /* Data from a CyAsMiscSetLowSpeedSDFreq or CyAsMiscSetHighSpeedSDFreq call. */

    CY_FUNCT_CB_MISC_RESERVELNABOOTAREA,        /* Data from a CyAsMiscSwitchPnandMode call */

    CY_FUNCT_CB_MISC_SETSDPOLARITY,             /* Data from a CyAsMiscSetSDPowerPolarity call */

    CY_FUNCT_CB_STOR_START,                     /* Data from a CyAsStorageStart call. */

    CY_FUNCT_CB_STOR_STOP,                      /* Data from a CyAsStorageStop call. */

    CY_FUNCT_CB_STOR_CLAIM,                     /* Data from a CyAsStorageClaim call. */

    CY_FUNCT_CB_STOR_RELEASE,                   /* Data from a CyAsStorageRelease call. */

    CY_FUNCT_CB_STOR_QUERYMEDIA,                /* Data from a CyAsStorageQueryMedia call. */

    CY_FUNCT_CB_STOR_QUERYBUS,                  /* Data from a CyAsStorageQueryBus call. */

    CY_FUNCT_CB_STOR_QUERYDEVICE,               /* Data from a CyAsStorageQueryDevice call. */

    CY_FUNCT_CB_STOR_QUERYUNIT,                 /* Data from a CyAsStorageQueryUnit call. */

    CY_FUNCT_CB_STOR_DEVICECONTROL,             /* Data from a CyAsStorageDeviceControl call. */

    CY_FUNCT_CB_STOR_SDREGISTERREAD,            /* Data from a CyAsStorageSDRegisterRead call. */

    CY_FUNCT_CB_STOR_PARTITION,                 /* Data from a CyAsStorageCreatePartition call. */

    CY_FUNCT_CB_STOR_GETTRANSFERAMOUNT,		/* Data from a CyAsStorageGetTransferAmount call. */

    CY_FUNCT_CB_STOR_ERASE,			/* Data from a CyAsStorageErase call. */

    CY_FUNCT_CB_ABORT_P2S_XFER,                 /* Data from a CyAsStorageCancelAsync call. */

    CY_FUNCT_CB_USB_START,                      /* Data from a CyAsUsbStart call. */

    CY_FUNCT_CB_USB_STOP,                       /* Data from a CyAsUsbStop call. */

    CY_FUNCT_CB_USB_CONNECT,                    /* Data from a CyAsUsbConnect call. */

    CY_FUNCT_CB_USB_DISCONNECT,                 /* Data from a CyAsUsbDisconnect call. */

    CY_FUNCT_CB_USB_SETENUMCONFIG,              /* Data from a CyAsUsbSetEnumConfig call. */

    CY_FUNCT_CB_USB_GETENUMCONFIG,              /* Data from a CyAsUsbGetEnumConfig call. */

    CY_FUNCT_CB_USB_SETDESCRIPTOR,              /* Data from a CyAsUsbSetDescriptor call. */

    CY_FUNCT_CB_USB_GETDESCRIPTOR,              /* Data from a CyAsUsbGetDescriptor call. */

    CY_FUNCT_CB_USB_COMMITCONFIG,               /* Data from a CyAsUsbCommitConfig call. */

    CY_FUNCT_CB_USB_GETNAK,			/* Data from a CyAsUsbGetNak call. */

    CY_FUNCT_CB_USB_GETSTALL,			/* Data from a CyAsUsbGetStall call. */

    CY_FUNCT_CB_USB_SIGNALREMOTEWAKEUP,         /* Data from a CyAsUsbSignalRemoteWakeup call. */

    CY_FUNCT_CB_USB_CLEARDESCRIPTORS,           /* Data from a CyAnUsbClearDescriptors call. */

    CY_FUNCT_CB_USB_SET_MSREPORT_THRESHOLD,     /* Data from a CyAnUsbSetMSReportThreshold call. */

    CY_FUNCT_CB_MTP_START,			/* Data from a CyAsMTPStart call. */

    CY_FUNCT_CB_MTP_STOP,			/* Data from a CyAsMTPStop call. */

    CY_FUNCT_CB_MTP_INIT_SEND_OBJECT,		/* Data from a CyAsMTPInitSendObject call. */

    CY_FUNCT_CB_MTP_CANCEL_SEND_OBJECT,		/* Data from a CyAsMTPCancelSendObject call. */

    CY_FUNCT_CB_MTP_INIT_GET_OBJECT,		/* Data from a CyAsMTPInitGetObject call. */

    CY_FUNCT_CB_MTP_CANCEL_GET_OBJECT,		/* Data from a CyAsMTPCancelGetObject call. */

    CY_FUNCT_CB_MTP_SEND_BLOCK_TABLE,		/* Data from a CyAsMTPSendBlockTable call. */

    CY_FUNCT_CB_MTP_STOP_STORAGE_ONLY,		/* Data from a CyAsMTPStopStorageOnly call. */

    CY_FUNCT_CB_NODATA = 0x40000000U,

    CY_FUNCT_CB_DATA =   0x20000000U

} CyAsFunctCBType ;

/* Summary

   This type specifies the general West Bridge function callback.

   Description

   This callback is supplied as an argument to all asynchronous functions in the API. It is

   called after the asynchronous function has completed. 

   See Also

   CyAsFunctCBType

*/

typedef void (*CyAsFunctionCallback)(

    CyAsDeviceHandle	handle,

    CyAsReturnStatus_t	status,

    uint32_t		client,

    CyAsFunctCBType	type,

    void*		data) ;

/* Summary

   This type specifies the general West Bridge event that has occurred.

   Description

   This type is used in the West Bridge misc callback function to indicate the type

   of callback.

   See Also

*/

typedef enum CyAsMiscEventType

{

    CyAsEventMiscInitialized = 0,		/* This event is sent when West Bridge has finished

						   initialization and is ready to respond to 

						   API calls. */

    CyAsEventMiscAwake,				/* This event is sent when West Bridge has left the

						   standby state and is ready to respond to commands

						   again. */

    CyAsEventMiscHeartBeat,                     /* This event is sent periodically from the firmware

                                                   to the processor. */

    CyAsEventMiscWakeup,                        /* This event is sent when the West Bridge has left the

                                                   suspend mode and is ready to respond to commands

                                                   again. */

    CyAsEventMiscDeviceMismatch                 /* This event is sent when the firmware image downloaded

                                                   cannot run on the active West Bridge device. */

} CyAsMiscEventType ;

/* Summary

   This type is the type of a callback function that is called when a West Bridge misc event occurs.

   Description

   At times West Bridge needs to inform the P port processor of events that have

   occurred.  These events are asynchronous to the thread of control on the P

   port processor and as such are generally delivered via a callback function that

   is called as part of an interrupt handler.  This type defines the type of function

   that must be provided as a callback function for West Bridge misc events.

   See Also

   * CyAsMiscEventType

*/

typedef void (*CyAsMiscEventCallback)(

    CyAsDeviceHandle		handle,		/* Handle to the device to configure */

    CyAsMiscEventType		ev,		/* The event type being reported */

    void *			evdata		/* The data assocaited with the event being reported */

) ;

#ifndef __doxygen__

/* Summary

   This enum provides info of various firmware trace levels.

   Description

   See Also

   * CyAsMiscSetTraceLevel

*/

enum {

    CYAS_FW_TRACE_LOG_NONE = 0,         /* Log nothing. */

    CYAS_FW_TRACE_LOG_STATE,            /* Log state information. */

    CYAS_FW_TRACE_LOG_CALLS,            /* Log function calls. */

    CYAS_FW_TRACE_LOG_STACK_TRACE,      /* Log function calls with args. */

    CYAS_FW_TRACE_MAX_LEVEL             /* Max trace level sentinel. */

};

#endif

/* Summary

   This enum lists the controllable GPIOs of the West Bridge device.

   Description

   The West Bridge device has GPIOs that can be used for user defined functions.

   This enumeration lists the GPIOs that are available on the device.

   Notes

   All of the GPIOs except UVALID can only be accessed when using West Bridge

   firmware images that support only SD/MMC/MMC+ storage devices. This

   functionality is not supported in firmware images that support NAND

   storage.

   See Also

   * CyAsMiscGetGpioValue

   * CyAsMiscSetGpioValue

 */

typedef enum {

    CyAsMiscGpio_0 = 0,                 /* GPIO[0] pin */

    CyAsMiscGpio_1,                     /* GPIO[1] pin */

    CyAsMiscGpio_Nand_CE,               /* NAND_CE pin, output only */

    CyAsMiscGpio_Nand_CE2,              /* NAND_CE2 pin, output only */

    CyAsMiscGpio_Nand_WP,               /* NAND_WP pin, output only */

    CyAsMiscGpio_Nand_CLE,              /* NAND_CLE pin, output only */

    CyAsMiscGpio_Nand_ALE,              /* NAND_ALE pin, output only */

    CyAsMiscGpio_SD_POW,                /* SD_POW pin, output only, do not drive low while storage is active */

    CyAsMiscGpio_UValid                 /* UVALID pin */

} CyAsMiscGpio;

/* Summary

   This enum lists the set of clock frequencies that are supported for working

   with low speed SD media.

   Description

   West Bridge firmware uses a clock frequency less than the maximum possible rate

   for low speed SD media.  This can be changed to a setting equal to the maximum

   frequency as desired by the user.  This enumeration lists the different

   frequency settings that are supported.

   See Also

   * CyAsMiscSetLowSpeedSDFreq

 */

typedef enum CyAsLowSpeedSDFreq

{

    CY_AS_SD_DEFAULT_FREQ = 0,          /* Approx. 21.82 MHz, default value */

    CY_AS_SD_RATED_FREQ                 /* 24 MHz */

} CyAsLowSpeedSDFreq ;

/* Summary

   This enum lists the set of clock frequencies that are supported for working

   with high speed SD media.

   Description

   West Bridge firmware uses a 48 MHz clock by default to interface with high speed

   SD/MMC media.  This can be changed to 24 MHz if so desired by the user.  This enum

   lists the different frequencies that are supported.

   See Also

   * CyAsMiscSetHighSpeedSDFreq

 */

typedef enum CyAsHighSpeedSDFreq

{

    CY_AS_HS_SD_FREQ_48,                /* 48 MHz, default value */

    CY_AS_HS_SD_FREQ_24                 /* 24 MHz */

} CyAsHighSpeedSDFreq ;

/* Summary

   Struct encapsulating all information returned by the CyAsMiscGetFirmwareVersion call.

   Description

   This struct encapsulates all return values from the asynchronous

   CyAsMiscGetFirmwareVersion call, so that a single data argument can be

   passed to the user provided callback function.

   See Also

   * CyAsMiscGetFirmwareVersion

 */

typedef struct CyAsGetFirmwareVersionData

{

    uint16_t 	major;		/* Return value for major version number for the firmware */

    uint16_t 	minor;		/* Return value for minor version number for the firmware */

    uint16_t 	build;		/* Return value for build version number for the firmware */

    uint8_t     mediaType;      /* Return value for media types supported in the current firmware */

    CyBool	isDebugMode;    /* Return value to indicate the release or debug mode of firmware */

} CyAsGetFirmwareVersionData ;

/*****************************************************************************

 * West Bridge Functions

 ****************************************************************************/

/* Summary

   This function creates a new West Bridge device and returns a handle to the device.

   Description

   This function initializes the API object that represents the West Bridge device and

   returns a handle to this device.  This handle is required for all West Bridge related

   functions to identify the specific West Bridge device.

   * Valid In Asynchronous Callback: NO

   Returns

   * CY_AS_ERROR_SUCCESS

   * CY_AS_ERROR_OUT_OF_MEMORY

*/

EXTERN CyAsReturnStatus_t

CyAsMiscCreateDevice(

        CyAsDeviceHandle *		handle_p,	/* Return value for handle to created device */

        CyAsHalDeviceTag		tag		/* The HAL specific tag for this device */

        ) ;

/* Summary

   This functions destroys a previously created West Bridge device.

   Description

   When an West Bridge device is created, an opaque handle is returned that represents

   the device.  This function destroys that handle and frees all resources associated

   with the handle.

   * Valid In Asynchronous Callback: NO

   Returns

   * CY_AS_ERROR_SUCCESS

   * CY_AS_ERROR_INVALID_HANDLE

   * CY_AS_ERROR_STILL_RUNNING - The USB or STORAGE stacks are still running, they must be stopped before the device can be destroyed

   * CY_AS_ERROR_DESTROY_SLEEP_CHANNEL_FAILED - the HAL layer failed to destroy a sleep channel

*/

EXTERN CyAsReturnStatus_t

CyAsMiscDestroyDevice(

        CyAsDeviceHandle		handle		/* Handle to the device to destroy */

        ) ;

/* Summary

   This function initializes the hardware for basic communication with West Bridge.

   Description

   This function intializes the hardware to establish basic communication with

   the West Bridge device.  This is always the first function called to initialize

   communication with the West Bridge device.

   * Valid In Asynchronous Callback: NO

   Returns

   * CY_AS_ERROR_SUCCESS - the basic initialization was completed

   * CY_AS_ERROR_INVALID_HANDLE

   * CY_AS_ERROR_IN_STANDBY

   * CY_AS_ERROR_ALREADY_RUNNING

   * CY_AS_ERROR_OUT_OF_MEMORY

   * CY_AS_ERROR_NO_ANTIOCH - cannot find the West Bridge device

   * CY_AS_ERROR_CREATE_SLEEP_CHANNEL_FAILED - the HAL layer falied to create a sleep channel

   See Also

   * CyAsDeviceConfig

*/

EXTERN CyAsReturnStatus_t

CyAsMiscConfigureDevice(

        CyAsDeviceHandle		handle,		/* Handle to the device to configure */

        CyAsDeviceConfig		*config_p	/* Configuration information */

        ) ;

/* Summary

   This function returns non-zero if West Bridge is in standby and zero otherwise.

   Description

   West Bridge supports a standby mode.  This function is used to query West Bridge to determine

   if West Bridge is in a standby mode.

   * Valid In Asynchronous Callback: YES

   Returns

   * CY_AS_ERROR_SUCCESS

   * CY_AS_ERROR_INVALID_HANDLE

*/

EXTERN CyAsReturnStatus_t

CyAsMiscInStandby(

        CyAsDeviceHandle		handle,		/* Handle to the device to configure */

        CyBool			        *standby	/* Return value for standby state */

        ) ;

/* Summary

   This function downloads the firmware to West Bridge device.

   Description

   This function downloads firmware from a given location and with a given size

   to the West Bridge device.  After the firmware is downloaded the West Bridge device is

   moved out of configuration mode causing the firmware to be executed.  It is an

   error to call this function when the device is not in configuration mode.  The

   device is in configuration mode on power up and may be placed in configuration

   mode after power up with a hard reset.

   Notes

   The firmware must be on a word align boundary.

   * Valid In Asynchronous Callback: YES (if cb supplied)

   * Nestable: YES

   Returns

   * CY_AS_ERROR_SUCCESS - the firmware was sucessfully downloaded

   * CY_AS_ERROR_INVALID_HANDLE

   * CY_AS_ERROR_NOT_CONFIGURED - the West Bridge device was not configured

   * CY_AS_ERROR_NOT_IN_CONFIG_MODE

   * CY_AS_ERROR_INVALID_SIZE - the size of the firmware exceeded 32768 bytes

   * CY_AS_ERROR_ALIGNMENT_ERROR

   * CY_AS_ERROR_IN_STANDBY - trying to download while in standby mode

   * CY_AS_ERROR_TIMEOUT

   See Also