--- /dev/null
+/* 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
projects / mv-sheeva.git / blobdiff