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