diff options
Diffstat (limited to 'drivers/staging/westbridge/astoria/include/linux/westbridge/cyasmtp.h')
| -rw-r--r-- | drivers/staging/westbridge/astoria/include/linux/westbridge/cyasmtp.h | 646 |
1 files changed, 646 insertions, 0 deletions
diff --git a/drivers/staging/westbridge/astoria/include/linux/westbridge/cyasmtp.h b/drivers/staging/westbridge/astoria/include/linux/westbridge/cyasmtp.h new file mode 100644 index 0000000..05d3449 --- /dev/null +++ b/drivers/staging/westbridge/astoria/include/linux/westbridge/cyasmtp.h @@ -0,0 +1,646 @@ +/* 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 |
