--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/omap3530/beagle_drivers/wb/api/src/cyaslowlevel.h Wed Mar 03 13:10:32 2010 +0000
@@ -0,0 +1,306 @@
+/* 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_ */