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

#define _INCLUDED_CYASUSB_H_

#include "cyasmisc.h"

#include "cyas_cplus_start.h"

/*@@Enumeration Model

  Summary

  The USB enumeration process is the process of communicating to the USB host information

  about the capabilities of the connected device.  This process is completed by servicing       

  requests for various types of descriptors.  In the software APIs described below, this        

  process is controlled in one of two ways.

  Description

  There are advantages to either type of enumeration and this is why both models are supported.  

  P Port processor based enumeraton gives the P port processor maximum control and flexibility 

  for providing USB configuration information.  However, this does require (near) real time data 

  responses from the P port processor during the enumeration process.  West Bridge based enumeration  

  requires no real time information from the P port processor, ensuring the fastest possible 

  enumeration times.

  * P Port Based Enumeration *

  The first method for handling USB enumeration is for the processor client to handle all 

  endpoint zero requests for descriptors.  This mode is configured by indicating to the API 

  that the processor wants to handle all endpoint zero requests.  This is done by setting 

  bit 0 in the end_point_mask to a 1.  The processor uses CyAsUsbReadDataAsync() to read 

  the request and CyAsUsbWriteDataAsync() to write the response.

  * West Bridge Based Enumeration *

  The second method for handling USB enumeration is the configuration information method.  

  Before enabling a connection from the West Bridge device to the USB connector, the P Port 

  processor sends information about the USB configuration to West Bridge through the configuration 

  APIs.  This information is stored within the West Bridge device.  When a USB cable is attached, 

  the West Bridge device then handles all descriptor requests based on the stored information.  

  Note that this method of enumeration only supports a single USB configuration.

  In either model of enumeration, the processor client is responsible for ensuring that

  the system meets USB Chapter 9 compliance requirements. This can be done by providing spec

  compliant descriptors, and handling any setup packets that are sent to the client

  appropriately.

  Mass storage class compliance will be ensured by the West Bridge firmware when the mass

  storage functionality is enabled.

*/

/*@@Endpoint Configuration

  Summary

  The West Bridge device has one 64-byte control endpoint, one 64-byte low bandwidth endpoint, four bulk

  endpoints dedicated for mass storage usage, and up to ten bulk/interrupt/isochronous

  endpoints that can be used for USB-to-Processor communication.

  Description

  The four storage endpoints (Endpoints 2, 4, 6 and 8) are reserved for accessing storage

  devices attached to West Bridge and are not available for use by the processor.  These are

  used implicitly when using the storage API to read/write to the storage media.

  Endpoint 0 is the standard USB control pipe used for all enumeration activity.  Though

  the endpoint buffer is not directly accessible from the processor, read/write activity

  can be performed on this endpoint through the API layers.  This endpoint is always

  configured as a bi-directional control endpoint.

  Endpoint 1 is a 64-byte endpoint that can be used for low bandwidth bulk/interrupt

  activity.  The physical buffer is not accessible from the processor, but can be read/written

  through the API.  As the data coming to this endpoint is being handled through the

  software layers, there can be loss of data if a read call is not waiting when an OUT

  packet arrives.

  Endpoints 3, 5, 7, 9, 10, 11, 12, 13, 14 and 15 are ten configurable endpoints

  mapped to parts of a total 4 KB FIFO buffer space on the West Bridge device.  This 4 KB

  physical buffer space is divided into up to four endpoints called PEP1, PEP2, PEP3 and PEP4

  in this software document.  There are multiple configurations in which this buffer space

  can be used, and the size and number of buffers available to each physical endpoint

  vary between these configurations.  See the West Bridge PDD for details on the buffer

  orientation corresponding to each configuration.

  * Note *

  PEPs 1, 2, 3 and 4 are called Physical EP 3, 5, 7 and 9 in the West Bridge PDD.  The

  sequential number scheme is used in the software to disambiguate these from the logical

  endpoint numbers, and also for convenience of array indexing.

*/

#if !defined(__doxygen__)

#endif

/* Summary

   This constants defines the maximum size of a USB descriptor when referenced via the

   CyAsUsbSetDescriptor or CyAsUsbGetDescriptor functions.

   See Also

   * CyAsUsbSetDescriptor

   * CyAsUsbGetDescriptor

*/

#define CY_AS_MAX_USB_DESCRIPTOR_SIZE				(128)

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

 * West Bridge Types

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

/* Summary

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

   callback for the inquiry request.

   Description

   When a SCSI inquiry request arrives via the USB connection and the P Port has asked

   to receive inquiry requests, this request is forwarded to the client via the USB

   callback.  This callback is called twice, once before the inquiry data is forwarded

   to the host (CyAsEventUsbInquiryBefore) and once after the inquiry has been sent to the

   USB host (CyAsEventUsbInquiryAfter).  The evdata parameter is a pointer to this data 

   structure.  

   *CyAsEventUsbInquiryBefore*

   If the client just wishes to see the inquiry request and associated data, then a simple 

   return from the callback will forward the inquiry response to the USB host.  If the 

   client wishes to change the data returned to the USB host, the updated parameter must 

   be set to CyTrue and the memory area address by the data parameter should be updated.  

   The data pointer can be changed to point to a new memory area and the length field 

   changed to change the amount of data returned from the inquiry request.  Note that the 

   data area pointed to by the data parameter must remain valid and the contents must

   remain consistent until after the CyAsEventUsbInquiryAfter event has occurred.  THE LENGTH

   MUST BE LESS THAN 192 BYTES OR THE CUSTOM INQUIRY RESPONSE WILL NOT BE RETURNED.  If the

   length is too long, the default inquiry response will be returned.

   *CyAsEventUsbInquiryAfter*

   If the client needs to free any data, this event signals that the data associated with

   the inquiry is no longer needed.

   See Also

   * CyAsUsbEventCallback

   * CyAsUsbRegisterCallback

*/

typedef struct CyAsUsbInquiryData

{

    CyAsBusNumber_t bus ;	/* The bus for the event */

    uint32_t device ;		/* The device the event */

    uint8_t evpd ;		/* The EVPD bit from the SCSI INQUIRY request */

    uint8_t codepage ;		/* The codepage in the inquiry request */

    CyBool updated ;		/* This bool must be set to CyTrue indicate that the inquiry

				   data was changed */

    uint16_t length ;		/* The length of the data */

    void *data ;		/* The inquiry data */

} CyAsUsbInquiryData ;

/* Summary

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

   callback for the unknown mass storage request.

   Description

   When a SCSI request is made that the mass storage firmware in West Bridge does not 

   know how to process, this request is passed to the processor for handling via 

   the usb callback.  This data structure is used to pass the request and the 

   associated response.  The user may set the status to indicate the status of the

   request.  The status value is the bCSWStatus value from the USB mass storage

   Command Status Wrapper (0 = command passed, 1 = command failed).  If the status

   is set to command failed (1), the sense information should be set as well.  For

   more information about sense information, see the USB mass storage specification

   as well as the SCSI specifications for block devices.  By default the status is

   initialized to 1 (failure) with a sense information of 05h/20h/00h which

   indicates INVALID COMMAND.

*/

typedef struct CyAsUsbUnknownCommandData

{

    CyAsBusNumber_t bus ;	/* The bus for the event */

    uint32_t device ;		/* The device for the event */

    uint16_t reqlen ;		/* The length of the requst (should be 16 bytes) */

    void *request ;		/* The request */

    uint8_t status ;		/* The returned status value for the command */

    uint8_t key ;		/* If status is failed, the sense key */

    uint8_t asc ;		/* If status is failed, the additional sense code */

    uint8_t ascq ;		/* If status if failed, the additional sense code qualifier */

} CyAsUsbUnknownCommandData ;

/* Summary

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

   callback for the start/stop request.

   Description

   When a SCSI start stop request arrives via the USB connection and the P Port has asked

   See Also

   * CyAsUsbEventCallback

   * CyAsUsbRegisterCallback

*/

typedef struct CyAsUsbStartStopData

{

    CyAsBusNumber_t bus ;	/* The bus for the event */

    uint32_t device ;		/* The device for the event */

    CyBool start ;		/* CyTrue means start request, CyFalse means stop request */

    CyBool loej ;		/* CyTrue means LoEj bit set, otherwise false */

} CyAsUsbStartStopData ;

/* Summary

   This data type is used to indicate which mass storage devices are enumerated.

   Description

   See Also

   * CyAsUsbEnumControl

   * CyAsUsbSetEnumConfig

*/

typedef enum CyAsUsbMassStorageEnum

{

    CyAsUsbNandEnum = 0x01,

    CyAsUsbSDEnum = 0x02,

    CyAsUsbMMCEnum = 0x04,

    CyAsUsbCEATAEnum = 0x08

} CyAsUsbMassStorageEnum ;

/* Summary

   This data type specifies the type of descriptor to transfer to the West Bridge device

   Description

   During enumeration, if West Bridge is handling enumeration, the West Bridge device needs to USB descriptors

   to complete the enumeration.  The function CyAsUsbSetDescriptor() is used to transfer the descriptors

   to the West Bridge device.  This type is an argument to that function and specifies which descriptor

   is being transferred.

   See Also

   * CyAsUsbSetDescriptor

   * CyAsUsbGetDescriptor

*/

typedef enum CyAsUsbDescType

{

    CyAsUsbDescDevice = 1,				/* A device descriptor - See USB 2.0 specification Chapter 9 */

    CyAsUsbDescDeviceQual = 2,				/* A device descriptor qualifier - See USB 2.0 specification Chapter 9 */

    CyAsUsbDescFSConfiguration = 3,			/* A configuration descriptor for FS operation - See USB 2.0 specification Chapter 9 */

    CyAsUsbDescHSConfiguration = 4,			/* A configuration descriptor for HS operation - See USB 2.0 specification Chapter 9 */

    CyAsUsbDescString = 5

} CyAsUsbDescType ;

/* Summary

   This type specifies the direction of an endpoint

   Description

   This type is used when configuring the endpoint hardware to specify the direction

   of the endpoint.

   See Also

   * CyAsUsbEndPointConfig

   * CyAsUsbSetEndPointConfig

   * CyAsUsbGetEndPointConfig

*/

typedef enum CyAsUsbEndPointDir

{

	CyAsUsbIn = 0,						/* The endpoint direction is IN (West Bridge -> USB Host) */

	CyAsUsbOut = 1,						/* The endpoint direction is OUT (USB Host -> West Bridge) */

	CyAsUsbInOut = 2					/* The endpoint direction is IN/OUT (valid only for EP 0 & 1) */

} CyAsUsbEndPointDir ;

/* Summary

   This type specifies the type of an endpoint

   Description

   This type is used when configuring the endpoint hardware to specify the type of

   endpoint.

   See Also

   * CyAsUsbEndPointConfig

   * CyAsUsbSetEndPointConfig

   * CyAsUsbGetEndPointConfig

*/

typedef enum CyAsUsbEndPointType

{

    CyAsUsbControl,

    CyAsUsbIso,

    CyAsUsbBulk,

    CyAsUsbInt

} CyAsUsbEndPointType ;

/* Summary

   This type is a structure used to indicate the top level configuration of the USB stack

   Description

   In order to configure the USB stack, the CyAsUsbSetEnumConfig() function is called to indicate

   how mass storage is to be handled, the specific number of interfaces to be supported if

   West Bridge is handling enumeration, and the end points of specifi interest.  This structure

   contains this information.

   See Also

   * CyAsUsbSetConfig

   * CyAsUsbGetConfig

   * <LINK Enumeration Model>

*/

typedef struct CyAsUsbEnumControl

{

    CyBool devices_to_enumerate[CY_AS_MAX_BUSES][CY_AS_MAX_STORAGE_DEVICES];

                                                        /* Designate which devices on which buses to enumerate */

    CyBool antioch_enumeration ;			/* If true, West Bridge will control enumeration.  If this is false the

							   P port controls enumeration.  If the P Port is controlling 

							   enumeration, traffic will be received via endpoint zero. */

    uint8_t mass_storage_interface ;			/* This is the interface # to use for the mass storage interface, 

							   if mass storage is enumerated.  If mass storage is not enumerated 

							   this value should be zero. */

    uint8_t mtp_interface ;			        /* This is the interface # to use for the MTP interface, 

							   if MTP is enumerated.  If MTP is not enumerated 

							   this value should be zero. */

    CyBool mass_storage_callbacks ;			/* If true, Inquiry, START/STOP, and unknown mass storage

							   requests cause a callback to occur for handling by the

							   baseband processor. */

} CyAsUsbEnumControl ;

/* Summary

   This structure is used to configure a single endpoint

   Description

   This data structure contains all of the information required to configure the West Bridge hardware

   associated with a given endpoint.

   See Also

   * CyAsUsbSetEndPointConfig

   * CyAsUsbGetEndPointConfig

*/

typedef struct CyAsUsbEndPointConfig

{

    CyBool enabled ;					/* If true, this endpoint is enabled */

    CyAsUsbEndPointDir dir ;				/* The direction of this endpoint */

    CyAsUsbEndPointType type ;				/* The type of endpoint */

    CyAsEndPointNumber_t physical ;			/* The physical endpoint #, 1, 2, 3, 4 */

    uint16_t size ;					/* The size of the endpoint in bytes */

} CyAsUsbEndPointConfig ;

/* Summary

   List of partition enumeration combinations that can be selected on a partitioned

   storage device.

   Description

   West Bridge firmware supports creating upto two partitions on mass storage

   devices connected to West Bridge.  When there are two partitions on a device,

   the user can choose which of these partitions should be made visible to a USB

   host through the mass storage interface.  This enumeration lists the various

   enumeration selections that can be made.

   See Also

   * CyAsStorageCreatePPartition

   * CyAsStorageRemovePPartition

   * CyAsUsbSelectMSPartitions

 */

typedef enum CyAsUsbMSType_t {

    CyAsUsbMSUnit0 = 0,                 /* Enumerate only partition 0 as CD (autorun) device */

    CyAsUsbMSUnit1,                     /* Enumerate only partition 1 as MS device (default setting) */

    CyAsUsbMSBoth                       /* Enumerate both units */

} CyAsUsbMSType_t ;

/* Summary

   This type specifies the type of USB event that has occurred

   Description

   This type is used in the USB event callback function to indicate the type of USB event

   that has occurred.  The callback function includes both this reasons for the callback

   and a data parameter associated with the reason.  The data parameter is used in a reason

   specific way and is documented below with each reason.

   See Also

   * CyAsUsbIoCallback

*/

typedef enum CyAsUsbEvent

{

    CyAsEventUsbSuspend,				/* This event is sent when West Bridge is put into the suspend

							   state by the USB host.  The data parameter is not used and

							   will be zero. */

    CyAsEventUsbResume,					/* This event is sent when West Bridge is taken out of the

							   suspend state by the USB host.  The data parameter is not

							   used and will be zero. */

    CyAsEventUsbReset,					/* This event is sent when a USB reset request is received

							   by the West Bridge device.  The data parameter is not used and

							   will be zero. */

    CyAsEventUsbSetConfig,				/* This event is sent when a USB set configuration request is made.

							   The data parameter is a pointer to a uint16_t that contains the 

							   configuration number.  The configuration number may be zero to 

							   indicate an unconfigure operation. */

    CyAsEventUsbSpeedChange,				/* This event is sent when the USB connection changes speed.  This is

							   generally a transition from full speed to high speed.  The parameter

							   to this event is a pointer to uint16_t that gives the speed of the

							   USB connection.  Zero indicates full speed, one indicates high speed */

    CyAsEventUsbSetupPacket,				/* This event is sent when a setup packet is received.  The data parameter

							   is a pointer to the eight bytes of setup data. */

    CyAsEventUsbStatusPacket,				/* This event is sent when a status packet is received.  The data

							   parameter is not used. */

    CyAsEventUsbInquiryBefore,				/* This event is sent when mass storage receives an inquiry

							   request and we have asked to see these requests. */

    CyAsEventUsbInquiryAfter,				/* This event is sent when mass storage has finished processing an

							   inquiry request and any data associated with the request is no longer

							   required. */

    CyAsEventUsbStartStop,				    /* This event is sent when mass storage receives a start/stop request and

							   we have asked to see these requests */

    CyAsEventUsbClearFeature,               /* This event is sent when a Clear Feature request is received.  The data

							   parameter is the endpoint number. */

    CyAsEventUsbUnknownStorage,			    /* This event is sent when mass storage receives a request that is not known

							   and we have asked to see these requests */

    CyAsEventUsbMSCProgress                 /* This event is sent when the read/write activity on the USB mass

                                                           storage has crossed a pre-set level */

} CyAsUsbEvent;

/* Summary

   This type is the type of a callback function that is called when a USB 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 USB events.

   See Also

   * CyAsUsbEvent

*/

typedef void (*CyAsUsbEventCallback)(

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

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

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

) ;

/* Summary

   This type is the callback function called after an asynchronous USB read/write operation

   Description

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

   asynchronous read or write operation.

   See Also

   * CyAsUsbReadDataAsync

   * CyAsUsbWriteDataAsync

   * CY_AS_ERROR_CANCELED

*/

typedef void (*CyAsUsbIoCallback)(

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

    CyAsEndPointNumber_t		ep,		/* The endpoint that has completed an operation */

    uint32_t				count,		/* THe amount of data transferred to/from USB */

    void *				buffer,		/* The data buffer for the operation */

    CyAsReturnStatus_t			status		/* The error status of the operation */

) ;

/* Summary

   This type is the callback function called after asynchronous API functions have completed.

   Description

   When calling API functions from callback routines (interrupt handlers usually) the async version of

   these functions must be used.  This callback is called when an asynchronous API function has completed.

*/

typedef void (*CyAsUsbFunctionCallback)(

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

    CyAsReturnStatus_t			status,		/* The error status of the operation */

    uint32_t				client		/* A client supplied 32 bit tag */

) ;

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

 * West Bridge Functions

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

/* Summary

   This function starts the USB stack

   Description

   This function initializes the West Bridge USB software stack if it has not yet been stared.  

   This initializes any required data structures and powers up any USB specific portions of 

   the West Bridge hardware.  If the stack had already been started, the USB stack reference count 

   is incremented.

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

   * Nestable: YES

   Notes

   This function cannot be called from any type of West Bridge callback.

   Returns

   * CY_AS_ERROR_NOT_CONFIGURED - the West Bridge device has not been configured

   * CY_AS_ERROR_NO_FIRMWARE - the firmware has not been loaded into West Bridge

   * CY_AS_ERROR_SUCCESS - the stack initialized and is ready for use

   * CY_AS_ERROR_TIMEOUT - a timeout occurred communicating with the West Bridge device

   See Also

   * CyAsUsbStop

*/

EXTERN CyAsReturnStatus_t 

CyAsUsbStart(

	CyAsDeviceHandle		handle,		/* Handle to the West Bridge device */

	CyAsFunctionCallback		cb,             /* The callback if async call */

	uint32_t			client          /* Client supplied data */

	) ;

/* Summary

   This function stops the USB stack

   Description

   This function decrements the reference count for the USB stack and if this count

   is zero, the USB stack is shut down.  The shutdown frees all resources associated

   with the USB stack.

   * Valid In Asynchronous Callback: NO

   Notes

   While all resources associated with the USB stack will be freed is a shutdown occurs,

   resources associated with underlying layers of the software will not be freed if they

   are shared by the storage stack and the storage stack is active.  Specifically the DMA manager,

   the interrupt manager, and the West Bridge communications module are all shared by both the

   USB stack and the storage stack.

   Returns