/* Cypress West Bridge API header file (cyasstorage.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_CYASSTORAGE_H_

#define _INCLUDED_CYASSTORAGE_H_

#include "cyasmedia.h"

#include "cyasmisc.h"

#include "cyas_cplus_start.h"

/*@@Storage APIs

  Summary

  This section documents the storage APIs supported by the West Bridge API.

  Description

  The storage API is based on some specific concepts which are referenced here.

  * <LINK Storage API Overview>

  * Addressing

  * Ownership

  * <LINK Asynchronous Versus Synchronous Operation>

*/

/*@@Storage API Overview

  Summary

  Storage devices are identified by media type. Each media type is considered a

  single logical device.

  Description

  Each media type has a consistent block size and consists

  of a set of logical blocks numbered from 0 to N - 1 where N is the size of the

  media type in blocks. The mass storage APIs defined below provide the

  capability to query for devices that are present, and read/write data to/from

  these devices.

*/

/*@@Addressing

  Summary

  Blocks within a storage device are address by a hierarchal block address.  This

  address consists of the bus number, physical device, logical unit, and finally

  block address.

  Description

  While currently only a single device of each media type is supported, the address

  space reserves space in the future for multiple devices of each type.  Therefore

  the second element of the address is the specific device being addressed within

  a given device type.  For this release of the software, this value will always be

  zero to address the first device.

  The third element of the address is the logical unit.  A device being managed

  by West Bridge can be partitioned into multiple logical units.  This partition

  information is stored on each device itself.  Currently, one of the storage devices

  managed by West Bridge can be partitioned into two logical units.

  Finally a logical block address is given within the logical unit to address an

  individual block.

*/

/*@@Ownership

  Summary

  While West Bridge supports concurrent block level operations from both the USB port and

  the processor port, this is not desirable in most situations as the file system

  contained on the storage media cannot be accessed concurrently.  To insure access

  by only one of USB and the processor, the West Bridge API provides for ownership of storage

  devices based on media type.

  Description

  The processor requests ownership of a given media type by calling CyAsStorageClaim().

  The firmware in West Bridge releases control of the media and signals the processor through

  the event callback registered with CyAsStorageRegisterCallback().  The specific event is

  the CyAsStorageProcessor. The processor can later release the media via a call to

  CyAsStorageRelease().  This call is immediate and no callback is required.

  If the processor has claimed storage and the USB port is connected, West Bridge will need to

  claim the storage to manage the mass storage device.  West Bridge requests the storage through

  the event callback registered with CyAsStorageRegisterCallback().  The specific event is

  CyAsStorageAntioch and is named as such to reflect the USB view of storage.  This callback

  is a request for the processor to release storage.  The storage is not actually released

  until the processor calls CyAsStorageRelease().

  Note that the CyAsStorageAntioch is only sent when the USB storage device is enumerated and

  NOT at every USB operation.  The ownership of a given storage media type is assumed to belong

  to the processor until the USB connection is established.  At that point, the storage ownership

  is transferred to West Bridge.  After the USB connection is broken, ownership can be transferred

  back to the processor.

*/

/*@@Asynchronous Versus Synchronous Operation

  Summary

  When read or write operations are performed to the storage devices, these operations may be

  synchronous or asynchronous.  A synchronous operation is an operation where the read or write

  operation is requested and the function does not return until the operation is complete.  This

  type of function is the easiest to use but does not provide for optimal usage of the P port

  processor time.

  Description

  An asynchronous operation is one where the function returns as soon as the request is started.

  The specific read and write request will complete at some time in the future and the P port

  processor will be notified via a callback function.  While asynchronous functions provide for

  much better usage of the CPU, these function have more stringent requirements for use.  First,

  any buffer use for data transfer must be valid from the function call to request the operation

  through when the callback function is called.  This basically implies that stack based buffers

  are not acceptable for asynchronous calls.  Second, error handling must be deferred until the

  callback function is called indicating any kind of error that may have occurred.

*/

/*@@Partitioning

  Summary

  West Bridge API and firmware support the creation of up to two logical partitions on one

  of the storage devices that are managed by West Bridge.  The partitions are managed through

  the CyAsStorageCreatePPartition and CyAsStorageRemovePPartition APIs.

  Description

  The CyAsStorageCreatePPartition API is used to divide the total storage on a storage

  device into two logical units or partitions.  Since the partition information is stored

  on the storage device in a custom format, partitions should only be created on fixed

  storage devices (i.e., no removable SD/MMC cards).  Any data stored on the device

  before the creation of the partition, is liable to be lost when a partition is created.

  The CyAsStorageRemovePPartition API is used to remove the stored partition information,

  so that all of the device's capacity is treated as a single partition again.

  When a storage device with two partitions (units) is being enumerated as a mass storage

  device through the West Bridge, it is possible to select the partitions to be made

  visible to the USB host.  This is done through the CyAsUsbSelectMSPartitions API.

*/

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

 * West Bridge Constants

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

/* Summary

   This constants indicates a raw device access to the read/write functions

   Description

   When performing reading and writing operations on the storage devices attached

   to West Bridge, there are cases where writes need to happen to raw devices, versus

   the units contained within a device.  This is specifically required to manage

   the partitions within physical devices.  This constant is used in calls to

   CyAsStorageRead(), CyAsStorageReadAsync(), CyAsStorageWrite() and

   CyAsStorageWriteAsync(), to indicate that the raw physical device is being

   accessed and not any specific unit on the device.

   See Also

   * CyAsStorageRead

   * CyAsStorageReadAsync

   * CyAsStorageWrite

   * CyAsStorageWriteAsync

*/

#define CY_AS_LUN_PHYSICAL_DEVICE						(0xffffffff)

/* Summary

   This constant represents the maximum DMA burst length supported on a storage

   endpoint

   Description

   West Bridge reserves separate endpoints for accessing storage media through the

   CyAsStorageRead() and CyAsStorageWrite() calls. The maximum size of these

   endpoints is always 512 bytes, regardless of status and speed of the USB

   connection.

*/

#define CY_AS_STORAGE_EP_SIZE                                                   (512)

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

 * West Bridge Types

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

/* Summary

   This type indicates the type of event in an event callback from West Bridge

   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 indicates the resonse for

   the call to the callback function.

   See Also

   * CyAsStorageEventCallback

   * CyAsStorageRegisterCallback

*/

typedef enum CyAsStorageEvent

{

	CyAsStorageAntioch,		    /*  This event occurs when the West Bridge device has

						detected a USB connect and has enumerated the

						storage controlled by West Bridge to the USB port.

						This event is the signal that the processor

						needs to release the storage media. West Bridge will

						not have control of the storage media until the

						processor calls CyAsReleaseStorage() to release

						the specific media. */

	CyAsStorageProcessor,		    /*  This event occurs when the processor has requested

						ownership of a given media type and West Bridge has

						released the media.  This event is an indicator

						that the transfer of ownership is complete and the

						processor now owns the given media type. */

	CyAsStorageRemoved,		    /*  This event occurs when a removable media type has

					        been removed. */

	CyAsStorageInserted,		    /*  This event occurs when a removable media type has

					        been inserted. */

	CyAsSdioInterrupt		    /*	This event occurs when the West Bridge device ercieves an

                                  		interrrupt from an SDIO card */

} CyAsStorageEvent ;

/* Summary

   This type gives the type of the operation in a storage operation callback

   Description

   This type is used in the callback function for asynchronous operation.  This type

   indicates whether it is a CyAsStorageRead() or CyAsStorageWrite() operation that

   has completed.

   See Also

   * <LINK Asynchronous Versus Synchronous Operation>

   * CyAsStorageRead

   * CyAsStorageWrite

*/

typedef enum CyAsOperType

{

    CyAsOpRead,							/* A data read operation */

    CyAsOpWrite							/* A data write operation */

} CyAsOperType ;

/* Summary

   This data structure describes a specific type of media

   Description

   This data structure is the return value from the CyAsStorageQueryDevice

   function.  This structure provides information about the specific storage

   device being queried.

   See Also

   * CyAsStorageQueryDevice

*/

typedef struct CyAsDeviceDesc

{

    CyAsMediaType   type ;		/* Type of device */

    CyBool	    removable ;		/* Is the device removable */

    CyBool	    writeable ;		/* Is the device writeable */

    uint16_t	    block_size ;	/* Basic block size for device */

    uint32_t	    number_units ;	/* Number of LUNs on the device */

    CyBool	    locked ;		/* Is the device password locked */

    uint32_t	    erase_unit_size ;   /* Size in bytes of an Erase Unit. Block erase operation

                                           is only supported for SD storage, and the erase_unit_size

                                           is invalid for all other kinds of storage. */

} CyAsDeviceDesc ;

/* Summary

   This data structure describes a specific unit on a specific type of media

   Description

   This data structure is the return value from the CyAsStorageQueryUnit

   function.  This structure provides information about the specific unit.

   See Also

   * CyAsStorageQueryUnit

*/

typedef struct CyAsUnitDesc

{

    CyAsMediaType type ;				/* Type of device */

    uint16_t block_size ;				/* Basic block size for device */

    uint32_t start_block ;				/* Physical start block for LUN */

    uint32_t unit_size ;				/* Number of blocks in the LUN */

} CyAsUnitDesc ;

/* Summary

   This function type defines a callback to be called after an asynchronous operation

   Description

   This function type defines a callback function that is called at the completion of any

   asynchronous read or write operation.

   See Also

   * CyAsStorageReadAsync()

   * CyAsStorageWriteAsync()

*/

typedef void (*CyAsStorageCallback)(

	CyAsDeviceHandle handle,			/* Handle to the device completing the storage operation */

	CyAsBusNumber_t bus,				/* The bus completing the operation */

	uint32_t device,				/* The device completing the operation */

	uint32_t unit,					/* The unit completing the operation */

	uint32_t block_number,				/* The block number of the completed operation */

	CyAsOperType op,				/* The type of operation */

	CyAsReturnStatus_t status			/* The error status */

	) ;

/* Summary

   This function type defines a callback to be called in the event of a storage related event

   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.

   See Also

   * CyAsStorageEvent

   * CyAsStorageRegisterCallback

*/

typedef void (*CyAsStorageEventCallback)(

    CyAsDeviceHandle handle,			/* Handle to the device sending the event notification */

    CyAsBusNumber_t  bus,			/* The bus where the event happened */

    uint32_t device,				/* The device where the event happened */

    CyAsStorageEvent evtype,			/* The event type */

    void *evdata				/* Event related data */

    ) ;

/* Summary

   This function type defines a callback to be called after an asynchronous sdio operation

   Description

   The Callback function is called at the completion of an asynchronous sdio read or write operation.

   See Also

   * CyAsSdioExtendedRead()

   * CyAsSdioExtendedWrite()

*/

typedef void (*CyAsSdioCallback)(

	CyAsDeviceHandle handle,	/* Handle to the device completing the storage operation */

	CyAsBusNumber_t bus,		/* The bus completing the operation */

	uint32_t device,		/* The device completing the operation */

	uint32_t function,		/* The function number of the completing the operation.

					   If the status of the operation is either CY_AS_ERROR_IO_ABORTED

					   or CY_AS_IO_SUSPENDED then the most significant word parameter will

					   contain the number of blocks still pending. */

	uint32_t address,		/* The base address of the completed operation */

	CyAsOperType op,		/* The type of operation */

	CyAsReturnStatus_t status	/* The status of the operation */

	) ;

/* Summary

   Enumeration of SD/MMC card registers that can be read through the API.

   Description

   Some of the registers on the SD/MMC card(s) attached to the West Bridge can be read

   through the API layers. This type enumerates the registers that can be read.

   See Also

   * CyAsStorageSDRegisterRead

 */

typedef enum CyAsSDCardRegType

{

    CyAsSDReg_OCR = 0,

    CyAsSDReg_CID,

    CyAsSDReg_CSD

} CyAsSDCardRegType ;

/* Summary

   Struct encapsulating parameters and return values for a CyAsStorageQueryDevice

   call.

   Description

   This struct holds the input parameters and the return values for an asynchronous

   CyAsStorageQueryDevice call.

   See Also

   * CyAsStorageQueryDevice

 */

typedef struct CyAsStorageQueryDeviceData

{

    CyAsBusNumber_t	bus ;		/* The bus with the device to query */

    uint32_t		device ;	/* The logical device number to query */

    CyAsDeviceDesc 	desc_p ;	/* The return value for the device descriptor */

} CyAsStorageQueryDeviceData ;

/* Summary

   Struct encapsulating parameters and return values for a CyAsStorageQueryUnit

   call.

   Description

   This struct holds the input parameters and the return values for an asynchronous

   CyAsStorageQueryUnit call.

   See Also

   * CyAsStorageQueryUnit

 */

typedef struct CyAsStorageQueryUnitData

{

    CyAsBusNumber_t	bus ;		/* The bus with the device to query */

    uint32_t	        device ;	/* The logical device number to query */

    uint32_t	        unit ;		/* The unit to query on the device */

    CyAsUnitDesc 	desc_p ;	/* The return value for the unit descriptor */

} CyAsStorageQueryUnitData ;

/* Summary

   Struct encapsulating the input parameter and return values for a

   CyAsStorageSDRegisterRead call.

   Description

   This struct holds the input parameter and return values for an asynchronous

   CyAsStorageSDRegisterRead call.

   See Also

   * CyAsStorageSDRegisterRead

 */

typedef struct CyAsStorageSDRegReadData

{

    uint8_t *buf_p;                     /* Pointer to the result buffer. */

    uint8_t  length;                    /* Length of data to be copied in bytes. */

} CyAsStorageSDRegReadData ;

/* Summary

   Controls which pins are used for card detection

   Description

   When a StorageDeviceControl call is made to enable or disable

   card detection this enum is passed in to control which pin

   is used for the detection.

   See Also

   * CyAsStorageDeviceControl

*/

typedef enum CyAsStorageCardDetect

{

    CyAsStorageDetect_GPIO,

    CyAsStorageDetect_SDAT_3

} CyAsStorageCardDetect ;

#ifndef __doxygen__

#define CyAsStorageDetect_GPIO_0 CyAsStorageDetect_GPIO

#define CY_AS_SD_REG_OCR_LENGTH         (4)     /* Length of OCR value in bytes. */

#define CY_AS_SD_REG_CID_LENGTH         (16)    /* Length of CID value in bytes. */

#define CY_AS_SD_REG_CSD_LENGTH         (16)    /* Length of CSD value in bytes. */

#define CY_AS_SD_REG_MAX_RESP_LENGTH    (10)    /* Max. length of register response in words. */

#endif

/* Summary

   This data structure is the data passed via the evdata paramater on a usb event

   callback for the mass storage device progress event.

   Description

   This data structure reports the number of sectors that have been written and read

   on the USB mass storage device since the last event report.  The corresponding

   event is only sent when either the number of writes, or the number of reads has

   crossed a pre-set threshold.

   See Also

   * CyAsUsbEventCallback

   * CyAsUsbRegisterCallback

*/

typedef struct CyAsMSCProgressData

{

    uint32_t wr_count;          /* Number of sectors written since the last event. */

    uint32_t rd_count;          /* Number of sectors read since the last event. */

} CyAsMSCProgressData ;

/* Summary

Flag to set Direct Write operation to read back from the address written to.

 See Also

 *CyAsSdioDirectWrite()

*/

#define CY_SDIO_RAW             (0x01)

/* Summary

Flag to set Extended Read and Write to perform IO using a FIFO

i.e. read or write from the specified address only.

 See Also

 *CyAsSdioExtendedRead()

 *CyAsSdioExtendedWrite()

*/

#define CY_SDIO_OP_FIFO         (0x00)

/* Summary

Flag to set Extended Read and Write to perform incremental

IO using the address provided as the base address.

 See Also

 *CyAsSdioExtendedRead()

 *CyAsSdioExtendedWrite()

*/

#define CY_SDIO_OP_INCR         (0x02)

/* Summary

Flag to set Extended Read and Write to Block Mode operation

 See Also

 *CyAsSdioExtendedRead()

 *CyAsSdioExtendedWrite()

*/

#define CY_SDIO_BLOCKMODE       (0x04)

/* Summary

Flag to set Extended Read and Write to Byte Mode operation

 See Also

 *CyAsSdioExtendedRead()

 *CyAsSdioExtendedWrite()

*/

#define CY_SDIO_BYTEMODE        (0x00)

/* Summary

Flag to force re/initialization of a function.

Description

If not set a call to CyAsSdioInitFunction()

will not initialize a function that has been previously initialized.

 See Also