/* 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_ */+
−