/* Cypress West Bridge API header file (cyasmtp.h)
## ===========================
## Copyright (C) 2010  Cypress Semiconductor
##
## This program is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License
## as published by the Free Software Foundation; either version 2
## of the License, or (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 51 Franklin Street
## Fifth Floor, Boston, MA  02110-1301, USA.
## ===========================
*/

#ifndef _INCLUDED_CYASMTP_H_
#define _INCLUDED_CYASMTP_H_

#include "cyasmisc.h"

#include "cyas_cplus_start.h"

/*@@Media Transfer Protocol (MTP) Overview
  Summary
  The MTP API has been designed to allow MTP enabled West Bridge
  devices to implement the MTP protocol while maintaining high
  performance. West Bridge has the capability to enter into a
  Turbo mode during a MTP SendObject or GetObject operation
  enabling it to directly stream the data into or out of the
  attached SD card with minimal involvement from the Processor.

  Description
  The MTP API is designed to act as a pass through implementation
  of the MTP protocol for all operations. Each MTP transaction
  received from the Host is passed through West Bridge and along
  to the Processor. The Processor can then respond to the
  transaction and pass data and/or responses back to the Host
  through West Bridge.

  The MTP API also allows for a high speed handling of MTP
  SendObject and GetObject operations, referred to as Turbo MTP.
  During a Turbo MTP operation West Bridge is responsible for
  reading or writing the data for the MTP operation directly from
  or to the SD card with minimal interaction from the Processor.
  The is done by having the Processor transfer a Block Table
  to West Bridge which contains the locations on the SD card that
  need to be read or written. During the handling of a Turbo
  Operation the Processor will then only periodically need to
  send a new Block Table to West Bridge when the first is used up.
  See the CyAsMTPInitSendObject and CyAsMTPInitGetObject functions
  for more details.

  In order to enable the MTP API you must first have a MTP enabled
  West Bridge loaded with MTP firmware. You then must start the USB
  and Storage APIs before starting the MTP API. See CyAsMTPStart
  for more details.
*/

/*@@Endpoints
  Summary
  When using MTP firmware endpoints 2 and 6 are dedicated
  to bulk MTP traffic and endpoint 1 is available for MTP
  events.

  Description
  When using a MTP enabled West Brdige device endpoints 2 and
  6 are made available for use to implement the MTP protocol.
  These endpoints have a few special restrictions noted below
  but otherwise the existing USB APIs can be used normally with
  these endpoints.

  1. CyAsUsbSetNak, CyAsUsbClearNak, and CyAsUsbGetNak are
	disabled for these endpoints
  2. During a turbo operation CyAsUsbSetStall, CyAsUsbClearStall,
	and CyAsUsbGetStall are disabled.

*/


/* Summary
   This constants defines the maximum number of
   entries in the Block Table used to describe
   the locations for Send/GetObject operations.

   See Also
   * CyAsMtpSendObject
   * CyAsMtpGetObject
*/
#define CY_AS_MAX_BLOCK_TABLE_ENTRIES 64

/* Summary
   Endpoint to be used for MTP reads from the USB host.
 */
#define CY_AS_MTP_READ_ENDPOINT		 (2)

/* Summary
   Endpoint to be used fro MTP writes to the USB host.
 */
#define CY_AS_MTP_WRITE_ENDPOINT		(6)

/******************************************
 * MTP Types
 ******************************************/

/* Summary
   The BlockTable used for turbo operations.

   Description
   This struct is used to specify the blocks
   to be used for both read/write and send/getObject
   operations.

   The start block is a starting Logical Block Address
   and num block is the number of blocks in that contiguous
   region.

   start_blocks[i]->[-------] <- start_blocks[i] + num_blocks[i]

   If you need fewer than CY_AS_MAX_BLOCK_TABLE_ENTRIES
   the remainder should be left empty. Empty is defined
   as num_blocks equal to 0.

   See Also
   * CyAsMTPInitSendObject
   * CyAsMTPInitGetObject

*/
typedef struct cy_as_mtp_block_table {
	uint32_t start_blocks[CY_AS_MAX_BLOCK_TABLE_ENTRIES];
	uint16_t num_blocks[CY_AS_MAX_BLOCK_TABLE_ENTRIES];
} cy_as_mtp_block_table;

/* Summary
   This type specifies the type of MTP event that has occurred.

   Description
   MTP events are used to communicate that West Bridge has
   either finished the handling of the given operation, or
   that it requires additional data to complete the operation.

   In no case does West Bridge send any MTP protocol responses,
   this always remain the responsibility of the client.

   See Also
   * CyAsMTPInitSendObject
   * CyAsMTPInitGetObject
   * CyAsMTPSendBlockTable

*/
typedef enum cy_as_mtp_event {
	/* This event is sent when West Bridge
	has finished writing the data from a
	send_object. west bridge will -not- send
	the MTP response. */
	cy_as_mtp_send_object_complete,

	/* This event is sent when West Bridge
	has finished sending the data for a
	get_object operation. west bridge will
	-not- send the MTP response. */
	cy_as_mtp_get_object_complete,

	/* This event is called when West Bridge
	needs a new block_table. this is only a
	notification, to transfer a block_table
	to west bridge the cy_as_mtp_send_block_table
	use the function. while west bridge is waiting
	for a block_table during a send_object it
	may need to NAK the endpoint. it is important
	that the cy_as_mtp_send_block_table call is made
	in a timely manner as eventually a delay
	will result in an USB reset. this event has
	no data */
	cy_as_mtp_block_table_needed
} cy_as_mtp_event;

/* Summary
   Data for the CyAsMTPSendObjectComplete event.

   Description
   Notification that a SendObject operation has been
   completed. The status of the operation is given
   (to distinguish between a cancelled and a success
   for example) as well as the block count. The blocks
   are used in order based on the current block table.
   If more than one block table was used for a given
   SendObject the count will include the total number
   of blocks written.

   This callback will be made only once per SendObject
   operation and it will only be called after all of
   the data has been committed to the SD card.

   See Also
   * CyAsMTPEvent

 */
typedef struct cy_as_mtp_send_object_complete_data {
	cy_as_return_status_t status;
	uint32_t byte_count;
	uint32_t transaction_id;
} cy_as_mtp_send_object_complete_data;

/*  Summary
	Data for the CyAsMTPGetObjectComplete event.

	Description
	Notification that a GetObject has finished. This
	event allows the P side to know when to send the MTP
	response for the GetObject operation.

	See Also
	* CyAsMTPEvent

*/
typedef struct cy_as_mtp_get_object_complete_data {
	cy_as_return_status_t status;
	uint32_t byte_count;
} cy_as_mtp_get_object_complete_data;

/*  Summary
	MTP Event callback.

	Description
	Callback used to communicate that a SendObject
	operation has finished.

	See Also
	* CyAsMTPEvent
*/
typedef void (*cy_as_mtp_event_callback)(
	cy_as_device_handle handle,
	cy_as_mtp_event evtype,
	void *evdata
	);

/* Summary
   This 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 (*cy_as_mtp_function_callback)(
	/* Handle to the device to configure */
	cy_as_device_handle	handle,
	/* The error status of the operation */
	cy_as_return_status_t	status,
	/* A client supplied 32 bit tag */
	uint32_t client
);

/**************************************
 * MTP Functions
 **************************************/

/* Summary
   This function starts the MTP stack.

   Description
   Initializes West Bridge for MTP activity and registers the MTP
   event callback.

   Before calling CyAsMTPStart, CyAsUsbStart and CyAsStorageStart must be
   called (in either order).

   MTPStart must be called before the device is enumerated. Please
   see the documentation for CyAsUsbSetEnumConfig and CyAsUsbEnumControl
   for details on enumerating a device for MTP.

   Calling MTPStart will not affect any ongoing P<->S traffic.

   This requires a MTP firmware image to be loaded on West Bridge.

   Returns
   * CY_AS_ERROR_SUCCESS
   * CY_AS_ERROR_INVALID_HANDLE
   * CY_AS_ERROR_NOT_CONFIGURED
   * CY_AS_ERROR_NO_FIRMWARE
   * CY_AS_ERROR_IN_SUSPEND
   * CY_AS_ERROR_INVALID_IN_CALLBACK
   * CY_AS_ERROR_STARTSTOP_PENDING
   * CY_AS_ERROR_NOT_RUNNING - CyAsUsbStart or CyAsStorageStart
   *	have not been called
   * CY_AS_ERROR_NOT_SUPPORTED - West Bridge is not running
   *	firmware with MTP support
   * CY_AS_ERROR_OUT_OF_MEMORY
   * CY_AS_ERROR_INVALID_RESPONSE


   See Also
   * CyAsMTPStop
   * CyAsUsbStart
   * CyAsStorageStart
   * CyAsUsbSetEnumConfig
   * CyAsUsbEnumControl
*/
cy_as_return_status_t
cy_as_mtp_start(
	cy_as_device_handle handle,
	cy_as_mtp_event_callback event_c_b,
	cy_as_function_callback cb,
	uint32_t client
	);


/*  Summary
	This function stops the MTP stack.

	Description
	Stops all MTP activity. Any ongoing transfers are
	canceled.

	This will not cause a UsbDisconnect but all
	MTP activity (both pass through and turbo) will
	stop.

	Returns
   * CY_AS_ERROR_SUCCESS
   * CY_AS_ERROR_INVALID_HANDLE
   * CY_AS_ERROR_NOT_CONFIGURED
   * CY_AS_ERROR_NO_FIRMWARE
   * CY_AS_ERROR_NOT_RUNNING
   * CY_AS_ERROR_IN_SUSPEND
   * CY_AS_ERROR_INVALID_IN_CALLBACK
   * CY_AS_ERROR_STARTSTOP_PENDING
   * CY_AS_ERROR_OUT_OF_MEMORY
   * CY_AS_ERROR_INVALID_RESPONSE


	See Also
	* CyAsMTPStart
*/
cy_as_return_status_t
cy_as_mtp_stop(
	cy_as_device_handle handle,
	cy_as_function_callback cb,
	uint32_t client
	);

/*  Summary
	This function sets up a Turbo SendObject operation.

	Description
	Calling this function will setup West Bridge to
	enable Tubo handling of the next SendObject
	operation received. This will pass down the initial
	block table to the firmware and setup a direct u->s
	write for the SendObject operation.

	If this function is not called before a SendObject
	operation is seen  the SendObject operation and data
	will be passed along to the P port like any other MTP
	command. It would then be the responsibility of the
	client to perform a normal StorageWrite call to
	store the data on the SD card. N.B. This will be
	very slow compared with the Turbo handling.

	The completion of this function only signals that
	West Bridge has been set up to receive the next SendObject
	operation. When the SendObject operation has been fully
	handled and the data written to the SD card a separate
	event will be triggered.

	Returns
	* CY_AS_ERROR_SUCCESS
	* CY_AS_ERROR_INVALID_HANDLE
	* CY_AS_ERROR_NOT_CONFIGURED
	* CY_AS_ERROR_NO_FIRMWARE
	* CY_AS_ERROR_IN_SUSPEND
	* CY_AS_ERROR_NOT_RUNNING
	* CY_AS_ERROR_OUT_OF_MEMORY
	* CY_AS_ERROR_ASYNC_PENDING
	* CY_AS_ERROR_INVALID_RESPONSE
	* CY_AS_ERROR_NOT_SUPPORTED - West Bridge is not running
	*	firmware with MTP support

	See Also
	* CyAsMTPCancelSendObject
	* CyAsMTPInitGetObject
	* CyAsMTPEvent
	* CyAsMTPSendBlockTable
*/
cy_as_return_status_t
cy_as_mtp_init_send_object(
	cy_as_device_handle handle,
	cy_as_mtp_block_table *blk_table,
	uint32_t num_bytes,
	cy_as_function_callback cb,
	uint32_t client
	);

/* Summary
   This function cancels an ongoing MTP operation.

   Description
   Causes West Bridge to cancel an ongoing SendObject
   operation. Note this is only a cancel to West Bridge,
   the MTP operation still needs to be canceled by
   sending a response.

   West Bridge will automatically set a Stall on the endpoint
   when the cancel is received.

   This function is only valid after CyAsMTPInitSendObject
   has been called, but before the CyAsMTPSendObjectComplete
   event has been sent.

   Returns
   * CY_AS_ERROR_SUCCESS
   * CY_AS_ERROR_INVALID_HANDLE
   * CY_AS_ERROR_NOT_RUNNING
   * CY_AS_ERROR_OUT_OF_MEMORY
   * CY_AS_ERROR_INVALID_RESPONSE
   * CY_AS_ERROR_NOT_SUPPORTED - West Bridge is not running
   *	firmware with MTP support
   * CY_AS_ERROR_NO_OPERATION_PENDING

   See Also
   * CyAsMTPInitSendObject
*/
cy_as_return_status_t
cy_as_mtp_cancel_send_object(
	cy_as_device_handle handle,
	cy_as_function_callback cb,
	uint32_t client
	);

/* Summary
   This function sets up a turbo GetObject operation.

   Description
   Called by the P in response to a GetObject
   operation. This provides West Bridge with the block
   addresses for the Object data that needs to be
   transferred.

   It is the responsibility of the Processor to send the MTP
   operation before calling CyAsMTPInitGetObject. West Bridge
   will then send the data phase of the transaction,
   automatically creating the required container for Data.
   Once all of the Data has been transferred a callback will
   be issued to inform the Processor that the Data phase has
   completed allowing it to send the required MTP response.

   If an entire Block Table is used then after the
   last block is transferred the CyAsMTPBtCallback
   will be called to allow an additional Block Table(s)
   to be specified.

   Returns
   * CY_AS_ERROR_SUCCESS
   * CY_AS_ERROR_INVALID_HANDLE
   * CY_AS_ERROR_NOT_CONFIGURED
   * CY_AS_ERROR_NO_FIRMWARE
   * CY_AS_ERROR_NOT_RUNNING
   * CY_AS_ERROR_IN_SUSPEND
   * CY_AS_ERROR_OUT_OF_MEMORY
   * CY_AS_ERROR_ASYNC_PENDING
   * CY_AS_ERROR_INVALID_RESPONSE
   * CY_AS_ERROR_NOT_SUPPORTED - West Bridge is not running
   *	firmware with MTP support

   See Also
   * CyAsMTPInitSendObject
   * CyAsMTPCancelGetObject
   * CyAsMTPEvent
   * CyAsMTPSendBlockTable
*/
cy_as_return_status_t
cy_as_mtp_init_get_object(
	cy_as_device_handle handle,
	cy_as_mtp_block_table *table_p,
	uint32_t num_bytes,
	uint32_t transaction_id,
	cy_as_function_callback cb,
	uint32_t client
	);

/* Summary
   This function cancels an ongoing turbo GetObject
   operation.

   Description
   Causes West Bridge to cancel an ongoing GetObject
   operation. Note this is only a cancel to West Bridge,
   the MTP operation still needs to be canceled by
   sending a response.

   This function is only valid after CyAsMTPGetSendObject
   has been called, but before the CyAsMTPGetObjectComplete
   event has been sent.

   Returns
   * CY_AS_ERROR_SUCCESS
   * CY_AS_ERROR_INVALID_HANDLE
   * CY_AS_ERROR_NOT_RUNNING
   * CY_AS_ERROR_OUT_OF_MEMORY
   * CY_AS_ERROR_INVALID_RESPONSE
   * CY_AS_ERROR_NOT_SUPPORTED - West Bridge is not running
   *	firmware with MTP support
   * CY_AS_ERROR_NO_OPERATION_PENDING

   See Also
   * CyAsMTPInitGetObject
*/
cy_as_return_status_t
cy_as_mtp_cancel_get_object(
	cy_as_device_handle handle,
	cy_as_function_callback cb,
	uint32_t client
	);

/* Summary
   This function is used to transfer a BlockTable as part of
   an ongoing MTP operation.

   Description
   This function is called in response to the
   CyAsMTPBlockTableNeeded event. This allows the client to
   pass in a BlockTable structure to West Bridge.

   The memory associated with the table will be copied and
   can be safely disposed of when the function returns if
   called synchronously, or when the callback is made if
   called asynchronously.

   This function is used for both SendObject and GetObject
   as both can generate the CyAsMTPBlockTableNeeded event.

   Returns
   * CY_AS_ERROR_SUCCESS
   * CY_AS_ERROR_INVALID_HANDLE
   * CY_AS_ERROR_NOT_CONFIGURED
   * CY_AS_ERROR_NO_FIRMWARE
   * CY_AS_ERROR_NOT_RUNNING
   * CY_AS_ERROR_IN_SUSPEND
   * CY_AS_ERROR_OUT_OF_MEMORY
   * CY_AS_ERROR_ASYNC_PENDING
   * CY_AS_ERROR_INVALID_RESPONSE
   * CY_AS_ERROR_NOT_SUPPORTED - West Bridge is not running
   *	firmware with MTP support

   See Also
   * CyAsMTPInitSendObject
   * CyAsMTPInitGetObject
*/
cy_as_return_status_t
cy_as_mtp_send_block_table(
	cy_as_device_handle handle,
	cy_as_mtp_block_table *table,
	cy_as_function_callback cb,
	uint32_t client
	);

/* Summary
   This function is used to mark the start of a storage
   read/write burst from the P port processor.

   Description
   This function is used to mark the start of a storage
   read/write burst from the processor. All USB host access
   into the mass storage / MTP endpoints will be blocked
   while the read/write burst is ongoing, and will be allowed
   to resume only after CyAsMTPStorageOnlyStop is called.
   The burst mode is used to reduce the firmware overhead
   due to configuring the internal data paths repeatedly,
   and can help improve performance when a sequence of
   read/writes is performed in a burst.

   This function will not generate a special mailbox request,
   it will only set a flag on the next Storage Read/Write
   operation. Until such a call is made West Bridge will
   continue to accept incoming packets from the Host.

   * Valid in Asynchronous Callback: YES

   Returns
   * CY_AS_ERROR_INVALID_HANDLE - Invalid West Bridge device
   *	handle was passed in.
   * CY_AS_ERROR_NOT_CONFIGURED - West Bridge device has not
   *	been configured.
   * CY_AS_ERROR_NO_FIRMWARE - Firmware is not active on West
   *	Bridge device.
   * CY_AS_ERROR_NOT_RUNNING - Storage stack is not running.
   * CY_AS_ERROR_SUCCESS - Burst mode has been started.

   See Also
   * CyAsStorageReadWriteBurstStop
 */
cy_as_return_status_t
cy_as_mtp_storage_only_start(
	/* Handle to the West Bridge device. */
	cy_as_device_handle handle
	);

/* Summary
   This function is used to mark the end of a storage read/write
   burst from the P port processor.

   Description
   This function is used to mark the end of a storage read/write
   burst from the processor.  At this point, USB access to the
   mass storage / MTP endpoints on the West Bridge device will be
   re-enabled.

   * Valid in Asynchronous Callback: NO

   Returns
   * CY_AS_ERROR_INVALID_HANDLE - Invalid West Bridge device handle
   *	was passed in.
   * CY_AS_ERROR_NOT_CONFIGURED - West Bridge device has not been
   *	configured.
   * CY_AS_ERROR_NO_FIRMWARE - Firmware is not active on West Bridge
   *	device.
   * CY_AS_ERROR_NOT_RUNNING - Storage stack is not running.
   * CY_AS_ERROR_INVALID_IN_CALLBACK - This API cannot be called
   *	from a callback.
   * CY_AS_ERROR_OUT_OF_MEMORY - Failed to allocate memory to
   *	process the request.
   * CY_AS_ERROR_TIMEOUT - Failed to send request to firmware.
   * CY_AS_ERROR_SUCCESS - Burst mode has been stopped.

   See Also
   * CyAsStorageReadWriteBurstStart
 */
cy_as_return_status_t
cy_as_mtp_storage_only_stop(
	/* Handle to the West Bridge device. */
	cy_as_device_handle handle,
	cy_as_function_callback cb,
	uint32_t client
	);

#include "cyas_cplus_end.h"

#endif