Bug 1996 - Contribution for West Bridge Astoria Symbian Storage Driver
this storage driver is for the West Bridge Astoria chipset. This device
has a USB, SD and processor port for communication with a baseband processor.
In our port, we connected this device DVK to the Beagleboard through the SPI
interface of the OMAP3. After driver installation, the Symbian OS can see an
external device or D: drive represented by the SD card. In this driver, the USB
interface is not used directly, though this may be the subject of future
contributions. The appropriate way to test the driver is to access the external
volume and do file read and write to it, pretty much the same way you would
test a thumb drive on your PC
/* Cypress West Bridge API header file (cyaslowlevel.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_CYASLOWLEVEL_H_
#define _INCLUDED_CYASLOWLEVEL_H_
/*@@Low Level Communications
Summary
The low level communications module is responsible for communications between
the West Bridge device and the P port processor. Communications is organized as
a series of requests and subsequent responses. For each request there is a
one and only one response. Requests may go from the West Bridge device to the P port
processor, or from the P Port processor to the West Bridge device.
Description
Requests are issued across what is called a context. A context is a single
channel of communications from one processor to another processor. There can
be only a single request outstanding on a context at a given time. Contexts
are used to identify subsystems that can only process a single request at a
time, but are independent of other contexts in the system. For instance, there
is a context for communicating storage commands from the P port processor to the
West Bridge device. There is also a context for communicating USB commands from
the P port processor to the West Bridge device.
Requests and responses are identical with the exception of the type bit in the
request/response header. If the type bit is one, the packet is a request. If
this bit is zero, the packet is a response. Also encoded within the header of
the request/response is the code. The code is a command code for a request, or
a response code for a response. For a request, the code is a function of the
context. The code 0 has one meaning for the storage context and a different
meaning for the USB context. The code is treated differently in the response.
If the code in the response is less than 16, then the meaning of the response is
global across all contexts. If the response is greater than or equal to 16,
then the response is specific to the associated context.
Requests and responses are transferred between processors through the mailbox
registers. It may take one or more cycles to transmit a complete request or
response. The context is encoded into each cycle of the transfer to insure the
receiving processor can route the data to the appropriate context for processing.
In this way, the traffic from multiple contexts can be multiplexed into a single
data stream through the mailbox registers by the sending processor, and
demultiplexed from the mailbox registers by the receiving processor.
* Firmware Assumptions *
The firmware assumes that mailbox contents will be consumed immediately. Therefore
for multi-cycle packets, the data is sent in a tight polling loop from the firmware.
This implies that the data must be read from the mailbox register on the P port side
and processed immediately or performance of the firmware will suffer. In order to
insure this is the case, the data from the mailboxes is read and stored immediately
in a per context buffer. This occurs until the entire packet is received at which
time the request packet is processed. Since the protocol is designed to allow for
only one outstanding packet at a time, the firmware can never be in a position of
waiting on the mailbox registers while the P port is processing a request. Only after
the response to the previous request is sent will another request be sent.
*/
#include "cyashal.h"
#include "cyasdevice.h"
#include "cyas_cplus_start.h"
/*
* Constants
*/
#define CY_AS_REQUEST_RESPONSE_CODE_MASK (0x00ff)
#define CY_AS_REQUEST_RESPONSE_CONTEXT_MASK (0x0F00)
#define CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT (8)
#define CY_AS_REQUEST_RESPONSE_TYPE_MASK (0x4000)
#define CY_AS_REQUEST_RESPONSE_LAST_MASK (0x8000)
#define CY_AS_REQUEST_RESPONSE_CLEAR_STR_FLAG (0x1000)
/*
* These macros extract the data from a 16 bit value
*/
#define CyAsMboxGetCode(c) ((uint8_t)((c) & CY_AS_REQUEST_RESPONSE_CODE_MASK))
#define CyAsMboxGetContext(c) ((uint8_t)(((c) & CY_AS_REQUEST_RESPONSE_CONTEXT_MASK) >> CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT))
#define CyAsMboxIsLast(c) ((c) & CY_AS_REQUEST_RESPONSE_LAST_MASK)
#define CyAsMboxIsRequest(c) (((c) & CY_AS_REQUEST_RESPONSE_TYPE_MASK) != 0)
#define CyAsMboxIsResponse(c) (((c) & CY_AS_REQUEST_RESPONSE_TYPE_MASK) == 0)
/*
* These macros (not yet written) pack data into or extract data
* from the m_box0 field of the request or response
*/
#define CyAsLLRequestResponse_SetCode(req, code) \
((req)->box0 = ((req)->box0 & ~CY_AS_REQUEST_RESPONSE_CODE_MASK) | \
(code & CY_AS_REQUEST_RESPONSE_CODE_MASK))
#define CyAsLLRequestResponse_GetCode(req) CyAsMboxGetCode((req)->box0)
#define CyAsLLRequestResponse_SetContext(req, context) \
((req)->box0 |= ((context) << CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT))
#define CyAsLLRequestResponse_SetClearStorageFlag(req) \
((req)->box0 |= CY_AS_REQUEST_RESPONSE_CLEAR_STR_FLAG)
#define CyAsLLRequestResponse_GetContext(req) CyAsMboxGetContext((req)->box0)
#define CyAsLLRequestResponse_IsLast(req) CyAsMboxIsLast((req)->box0)
#define CYAnLLRequestResponse__SetLast(req) \
((req)->box0 |= CY_AS_REQUEST_RESPONSE_LAST_MASK)
#define CyAsLLRequestResponse_IsRequest(req) CyAsMboxIsRequest((req)->box0)
#define CyAsLLRequestResponse_SetRequest(req) \
((req)->box0 |= CY_AS_REQUEST_RESPONSE_TYPE_MASK)
#define CyAsLLRequestResponse_SetResponse(req) \
((req)->box0 &= ~CY_AS_REQUEST_RESPONSE_TYPE_MASK)
#define CyAsLLRequestResponse_IsResponse(req) CyAsMboxIsResponse((req)->box0)
#define CyAsLLRequestResponse_GetWord(req, offset) ((req)->data[(offset)])
#define CyAsLLRequestResponse_SetWord(req, offset, value) ((req)->data[(offset)] = value)
typedef enum CyAsRemoveRequestResult_t
{
CyAsRemoveRequestSucessful,
CyAsRemoveRequestInTransit,
CyAsRemoveRequestNotFound
} CyAsRemoveRequestResult_t ;
/* Summary
Start the low level communications module
Description
*/
CyAsReturnStatus_t
CyAsLLStart(
CyAsDevice *dev_p
) ;
CyAsReturnStatus_t
CyAsLLStop(
CyAsDevice *dev_p
) ;
CyAsLLRequestResponse *
CyAsLLCreateRequest(
CyAsDevice *dev_p,
uint16_t code,
uint8_t context,
uint16_t length /* Length of the request in 16 bit words */
) ;
void
CyAsLLInitRequest(
CyAsLLRequestResponse *req_p,
uint16_t code,
uint16_t context,
uint16_t length) ;
void
CyAsLLInitResponse(
CyAsLLRequestResponse *req_p,
uint16_t length) ;
void
CyAsLLDestroyRequest(
CyAsDevice *dev_p,
CyAsLLRequestResponse *) ;
CyAsLLRequestResponse *
CyAsLLCreateResponse(
CyAsDevice *dev_p,
uint16_t length /* Length of the request in 16 bit words */
) ;
CyAsRemoveRequestResult_t
CyAsLLRemoveRequest(
CyAsDevice *dev_p,
CyAsContext *ctxt_p,
CyAsLLRequestResponse *req_p,
CyBool force
) ;
void
CyAsLLRemoveAllRequests(CyAsDevice *dev_p,
CyAsContext *ctxt_p) ;
void
CyAsLLDestroyResponse(
CyAsDevice *dev_p,
CyAsLLRequestResponse *) ;
CyAsReturnStatus_t
CyAsLLSendRequest(
CyAsDevice * dev_p, /* The West Bridge device */
CyAsLLRequestResponse * req, /* The request to send */
CyAsLLRequestResponse * resp, /* Storage for a reply, must be sure it is of sufficient size */
CyBool sync, /* If true, this is a sync request */
CyAsResponseCallback cb /* Callback to call when reply is received */
) ;
CyAsReturnStatus_t
CyAsLLSendRequestWaitReply(
CyAsDevice * dev_p, /* The West Bridge device */
CyAsLLRequestResponse * req, /* The request to send */
CyAsLLRequestResponse * resp /* Storage for a reply, must be sure it is of sufficient size */
) ;
/* Summary
This function registers a callback function to be called when a request arrives on a given
context.
Description
Returns
* CY_AS_ERROR_SUCCESS
*/
extern CyAsReturnStatus_t
CyAsLLRegisterRequestCallback(
CyAsDevice *dev_p,
uint8_t context,
CyAsResponseCallback cb
) ;
/* Summary
This function packs a set of bytes given by the data_p pointer into a request, reply
structure.
*/
extern void
CyAsLLRequestResponse_Pack(
CyAsLLRequestResponse *req, /* The destintation request or response */
uint32_t offset, /* The offset of where to pack the data */
uint32_t length, /* The length of the data to pack in bytes */
void *data_p /* The data to pack */
) ;
/* Summary
This function unpacks a set of bytes from a request/reply structure into a segment of memory given
by the data_p pointer.
*/
extern void
CyAsLLRequestResponse_Unpack(
CyAsLLRequestResponse *req, /* The source of the data to unpack */
uint32_t offset, /* The offset of the data to unpack */
uint32_t length, /* The length of the data to unpack in bytes */
void *data_p /* The destination of the unpack operation */
) ;
/* Summary
This function sends a status response back to the West Bridge device in response to a
previously send request
*/
extern CyAsReturnStatus_t
CyAsLLSendStatusResponse(
CyAsDevice *dev_p, /* The West Bridge device */
uint8_t context, /* The context to send the response on */
uint16_t code, /* The success/failure code to send */
uint8_t clear_storage) ; /* Flag to clear wait on storage context */
/* Summary
This function sends a response back to the West Bridge device.
Description
This function sends a response back to the West Bridge device. The response is sent on the
context given by the 'context' variable. The code for the response is given by the 'code'
argument. The data for the response is given by the data and length arguments.
*/
extern CyAsReturnStatus_t
CyAsLLSendDataResponse(
CyAsDevice *dev_p, /* The West Bridge device */
uint8_t context, /* The context to send the response on */
uint16_t code, /* The response code to use */
uint16_t length, /* The length of the data for the response */
void *data /* The data for the response */
) ;
/* Summary
This function removes any requests of the given type from the given context.
Description
This function removes requests of a given type from the context given via the
context number.
*/
extern CyAsReturnStatus_t
CyAsLLRemoveEpDataRequests(
CyAsDevice *dev_p, /* The West Bridge device */
CyAsEndPointNumber_t ep
) ;
#include "cyas_cplus_end.h"
#endif /* _INCLUDED_CYASLOWLEVEL_H_ */