/* Cypress West Bridge API header file (cyashaldoc.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_CYASHALDOC_H_

#define _INCLUDED_CYASHALDOC_H_

#include "cyashaldef.h"

/*@@Hardware Abstraction Layer (HAL)

    Summary

    This software module is supplied by the user of the West Bridge API.  This module contains the

    software that is specific to the hardware implementation or operating system of the client

    system.

    * Sleep Channels *

    A sleep channel is a operating system object that provides that capability for one

    thread or process to sleep while waiting on the completion of some hardware event. The

    hardware event is usually processed by a hardware interrupt and the interrupt handler

    then wakes the thread or process that is sleeping.

    A sleep channel provides the mechanism for this operation.  A sleep channel is created and 

    initialized during the API initialization. When the API needs to wait for the hardware, the 

    API performs a SleepOn() operation on the sleep channel.  When hardware event occurs, an 

    interrupt handler processes the event and then performs a Wake() operation on the sleep channel 

    to wake the sleeping process or thread.

    * DMA Model *

    When the West Bridge API needs to transfer USB or storage data to/from the West Bridge device, this is 

    done using a "DMA" operation.  In this context the term DMA is used loosely as the West Bridge 

    API does not really care if the data is transferred using a burst read or write operation,

    or if the data is transferred using programmed I/O operations.  When a "DMA" operation is

    needed, the West Bridge API calls either CyAsHalDmaSetupRead() or CyAsHalDmaSetupWrite() depending

    on the direction of the data flow.  The West Bridge API expects the "DMA" operation requested in

    the call to be completed and the registered "DMA complete" callback to be called.

    The West Bridge API looks at several factors to determine the size of the "DMA" request to

    pass to the HAL layer.  First the West Bridge API calls CyAsHalDmaMaxRequestSize() to determine

    the maximum amount of data the HAL layer can accept for a "DMA" operation on the requested

    endpoint.  The West Bridge API will never exceed this value in a "DMA" request to the HAL

    layer.  The West Bridge API also sends the maximum amount of data the West Bridge device can

    accept as part of the "DMA" request.  If the amount of data in the "DMA" request to the HAL

    layer exceeds the amount of data the West Bridge device can accept, it is expected that the

    HAL layer has the ability to break the request into multiple operations.

    If the HAL implementation requires the API to handle the size of the "DMA" requests for

    one or more endpoints, the value CY_AS_DMA_MAX_SIZE_HW_SIZE can be returned from the

    CyAsHalDmaMaxRequestSize() call.  In this case, the API assumes that the maximum size of

    each "DMA" request should be limited to the maximum that can be accepted by the endpoint

    in question.

    Notes

    See the <install>/api/hal/scm_kernel/cyashalscm_kernel.c file for an example of how 

    the DMA request size can be managed by the HAL implementation.

    * Interrupt Handling *

    The HAL implementation is required to handle interrupts arriving from the West Bridge device,

    and call the appropriate handlers.  If the interrupt arriving is one of PLLLOCKINT,

    PMINT, MBINT or MCUINT, the CyAsIntrServiceInterrupt API should be called to service the

    interrupt.  If the interrupt arriving is DRQINT, the HAL should identify the endpoint

    corresponding to which the DRQ is being generated and perform the read/write transfer

    from the West Bridge. See the <install>/api/hal/scm_kernel/cyashalscm_kernel.c or

    <install>/api/hal/fpga/cyashalfpga.c reference HAL implementations for examples.

    The HAL implementation can choose to poll the West Bridge interrupt status register instead

    of using interrupts.  In this case, the polling has to be performed from a different

    thread/task than the one running the APIs.  This is required because there are API calls

    that block on the reception of data from the West Bridge, which is delivered only through

    the interrupt handlers.

    * Required Functions *

    This section defines the types and functions that must be supplied in order to provide a

    complete HAL layer for the West Bridge API.

    Types that must be supplied:

    * CyAsHalSleepChannel

    Hardware functions that must be supplied:

    * CyAsHalWriteRegister

    * CyAsHalReadRegister

    * CyAsHalDmaSetupWrite

    * CyAsHalDmaSetupRead

    * CyAsHalDmaCancelRequest

    * CyAsHalDmaRegisterCallback

    * CyAsHalDmaMaxRequestSize

    * CyAsHalSetWakeupPin

    * CyAsHalSyncDeviceClocks

    * CyAsHalInitDevRegisters

    * CyAsHalReadRegsBeforeStandby

    * CyAsHalRestoreRegsAfterStandby

    Operating system functions that must be supplied:

    * CyAsHalAlloc

    * CyAsHalFree

    * CyAsHalCBAlloc

    * CyAsHalCBFree

    * CyAsHalMemSet

    * CyAsHalCreateSleepChannel

    * CyAsHalDestroySleepChannel

    * CyAsHalSleepOn

    * CyAsHalWake

    * CyAsHalDisableInterrupts

    * CyAsHalEnableInterrupts

    * CyAsHalSleep150

    * CyAsHalSleep

    * CyAsHalAssert

    * CyAsHalPrintMessage

    * CyAsHalIsPolling

*/

/* Summary

   This is the type that represents a sleep channel

   Description

   A sleep channel is an operating system object that, when a thread of control waits on the

   sleep channel, the thread sleeps until another thread signals the sleep object.  This object

   is generally used when a high level API is called and must wait for a response that is 

   supplied in an interrupt handler.  The thread calling the API is put into a sleep state and

   when the reply arrives via the interrupt handler, the interrupt handler wakes the sleeping

   thread to indicate that the expect reply is available.

*/

typedef struct CyAsHalSleepChannel

{

    int					m_channel ;	/* This structure is filled in with OS specific information

							   to implementat a sleep channel */

} CyAsHalSleepChannel ;

/* Summary

   This function is called to write a register value

   Description

   This function is called to write a specific register to a specific value.  The tag identifies the

   device of interest.  The address is relative to the base address of the West Bridge device. 

   Returns

   Nothing

   See Also

   * CyAsHalDeviceTag

   * CyAsHalReadRegister

*/

EXTERN void

CyAsHalWriteRegister(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    uint16_t				addr,		/* The address we are writing to */

    uint16_t				value		/* The value to write to the register */

    ) ;

/* Summary

   This function is called to read a register value

   Description

   This function is called to read the contents of a specific register.  The tag identifies the

   device of interest.  The address is relative to the base address of the West Bridge device.

   Returns

   Contents of the register

   See Also

   * CyAsHalDeviceTag

   * CyAsHalWriteRegister

*/

EXTERN uint16_t

CyAsHalReadRegister(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    uint16_t				addr		/* The address we are writing to */

    ) ;

/* Summary

   This function initiates a DMA write operation to write to West Bridge

   Description

   This function initiates a DMA write operation.  The request size will not exceed the value the HAL

   layer returned via CyAsHalDmaMaxRequestSize().  This request size may exceed the size of what the

   West Bridge device will accept as one packet and the HAL layer may need to divide the request into

   multiple hardware DMA operations.

   Returns

   None

   See Also

   * CyAsHalDmaSetupRead

   * CyAsHalDmaMaxRequestSize

*/

EXTERN void

CyAsHalDmaSetupWrite(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    CyAsEndPointNumber_t		ep,		/* The endpoint we are writing to */

    void *				buf_p,		/* The data to write via DMA */

    uint32_t				size,		/* The size of the data at buf_p */

    uint16_t				maxsize		/* The maximum amount of data that the endpoint can accept as one packet */

    ) ;

/* Summary

   This function initiates a DMA read operation from West Bridge

   Description

   This function initiates a DMA read operation.  The request size will not exceed the value the 

   HAL layer returned via CyAsHalDmaMaxRequestSize().  This request size may exceed the size of what

   the Anitoch will accept as one packet and the HAL layer may need to divide the request into multiple

   hardware DMA operations.

   Returns

   None

   See Also

   * CyAsHalDmaSetupRead

   * CyAsHalDmaMaxRequestSize

*/

EXTERN void

CyAsHalDmaSetupRead(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    CyAsEndPointNumber_t		ep,		/* The endpoint we are reading from */

    void *				buf_p,		/* The buffer to read data into */

    uint32_t				size,		/* The amount of data to read */

    uint16_t				maxsize		/* The maximum amount of data that the endpoint can provide in one DMA operation */

    ) ;

/* Summary

   This function cancels a pending DMA request

   Description

   This function cancels a pending DMA request that has been passed down to the hardware.  The HAL layer

   can elect to physically cancel the request if possible, or just ignore the results of the request if it

   is not possible.

   Returns

   None

*/

EXTERN void

CyAsHalDmaCancelRequest(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    CyAsEndPointNumber_t		ep		/* The endpoint we are reading from */

    ) ;

/* Summary

   This function registers a callback function to be called when a DMA request is completed

   Description

   This function registers a callback that is called when a request issued via CyAsHalDmaSetupWrite() or

   CyAsHalDmaSetupRead() has completed.

   Returns

   None

   See Also

   * CyAsHalDmaSetupWrite

   * CyAsHalDmaSetupRead

*/

EXTERN void

CyAsHalDmaRegisterCallback(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    CyAsHalDmaCompleteCallback		cb		/* The callback to call when a request has completed */

    ) ;

/* Summary

   This function returns the maximum size of a DMA request that can be handled by the HAL.

   Description

   When DMA requests are passed to the HAL layer for processing, the HAL layer may have a limit

   on the size of the request that can be handled.  This function is called by the DMA manager

   for an endpoint when DMA is enabled to get the maximum size of data the HAL layer can handle.

   The DMA manager insures that a request is never sent to the HAL layer that exceeds the size

   returned by this function.

   Returns

   the maximum size of DMA request the HAL layer can handle

*/

EXTERN uint32_t

CyAsHalDmaMaxRequestSize(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    CyAsEndPointNumber_t		ep		/* The endpoint of interest */

    ) ;

/* Summary

   This function sets the WAKEUP pin to a specific state on the West Bridge device.

   Description

   In order to enter the standby mode, the WAKEUP pin must be de-asserted.  In order to resume from

   standby mode, the WAKEUP pin must be asserted.  This function provides the mechanism to do

   this.

   Returns

   1 if the pin was changed, 0 if the HAL layer does not support changing this pin

*/

EXTERN uint32_t

CyAsHalSetWakeupPin(

    CyAsHalDeviceTag			tag,		/* The tag to ID a specific West Bridge device */

    CyBool				state		/* The desired state of the wakeup pin */

    ) ;

/* Summary

   Synchronise the West Bridge device clocks to re-establish device connectivity.

   Description

   When the Astoria bridge device is working in SPI mode, a long period of inactivity

   can cause a loss of serial synchronisation between the processor and Astoria.  This

   function is called by the API when it detects such a condition, and is expected to take

   the action required to re-establish clock synchronisation between the devices.

   Returns

   CyTrue if the attempt to re-synchronise is successful, CyFalse if not.

 */

EXTERN CyBool

CyAsHalSyncDeviceClocks(

    CyAsHalDeviceTag                    tag,            /* The tag to ID a specific West Bridge device */

    ) ;

/* Summary

   Initialize West Bridge device registers that may have been modified while the device

   was in standby.

   Description

   The content of some West Bridge registers may be lost when the device is placed in

   standby mode.  This function restores these register contents so that the device can

   continue to function normally after it wakes up from standby mode.

   This function is required to perform operations only when the API is being used with

   the Astoria device in one of the PNAND modes or in the PSPI mode.  It can be a

   no-operation in all other cases.

   Returns

   None

 */

EXTERN void

CyAsHalInitDevRegisters(

    CyAsHalDeviceTag                    tag,                    /* The tag to ID a specific West Bridge device */

    CyBool                              is_standby_wakeup       /* Indicates whether this is a wake-up from standby. */

    ) ;

/* Summary

   This function reads a set of P-port accessible device registers and stores their value

   for later use.

   Description

   The West Bridge Astoria device silicon has a known problem when operating in SPI mode

   on the P-port, where some of the device registers lose their value when the device

   goes in and out of standby mode.  The suggested work-around is to reset the Astoria

   device as part of the wakeup procedure from standby.

   This requires that the values of some of the P-port accessible registers be restored to

   their pre-standby values after it has been reset.  This HAL function can be used to read

   and store the values of these registers at the point where the device is being placed

   in standby mode.

   Returns

   None

   See Also

   * CyAsHalRestoreRegsAfterStandby

 */

EXTERN void

CyAsHalReadRegsBeforeStandby(

    CyAsHalDeviceTag                    tag                     /* The tag to ID a specific West Bridge device */

    ) ;

/* Summary

   This function restores the old values to a set of P-port accessible device registers.

   Description

   This function is part of the work-around to a known West Bridge Astoria device error when

   operating in SPI mode on the P-port.  This function is used to restore a set of P-port

   accessible registers to the values they had before the device was placed in standby

   mode.

   Returns

   None

   See Also

   * CyAsHalRestoreRegsAfterStandby

 */

EXTERN void

CyAsHalRestoreRegsAfterStandby(

    CyAsHalDeviceTag                    tag                     /* The tag to ID a specific West Bridge device */

    ) ;

/*

 * The functions below this comment are part of the HAL layer, as the HAL layer consists of the

 * abstraction to both the hardware platform and the operating system.  However; the functions below

 * this comment all relate to the operating environment and not specifically to the hardware platform

 * or specific device.

 */

/* Summary

   This function allocates a block of memory

   Description

   This is the HAL layer equivalent of the malloc() function.

   Returns

   a pointer to a block of memory

   See Also

   * CyAsHalFree

*/

EXTERN void *

CyAsHalAlloc(

    uint32_t				size		/* The size of the memory block to allocate */

    ) ;

/* Summary

   This function frees a previously allocated block of memory

   Description

   This is the HAL layer equivalent of the free() function.

   Returns

   None

   See Also

   * CyAsHalAlloc

*/

EXTERN void

CyAsHalFree(

    void *				ptr		/* Pointer to a memory block to free */

    ) ;

/* Summary

   This function is a malloc equivalent that can be used from an

   interrupt context.

   Description

   This function is a malloc equivalent that will be called from the

   API in callbacks. This function is required to be able to provide

   memory in interrupt context.

   Notes

   For platforms where it is not possible to allocate memory in interrupt

   context, we provide a reference allocator that takes memory during

   initialization and implements malloc/free using this memory.

   See the <install>/api/hal/fpga/cyashalblkalloc.[ch] files for the

   implementation, and the <install>/api/hal/fpga/cyashalfpga.c file

   for an example of the use of this allocator.

   Returns

   A pointer to the allocated block of memory

   See Also

   * CyAsHalCBFree

   * CyAsHalAlloc

*/

EXTERN void *

CyAsHalCBAlloc(

    uint32_t                            size            /* The size of the memory block to allocate */

    ) ;

/* Summary

   This function frees the memory allocated through the CyAsHalCBAlloc

   call.

   Description

   This function frees memory allocated through the CyAsHalCBAlloc

   call, and is also required to support calls from interrupt

   context.

   Returns

   None

   See Also

   * CyAsHalCBAlloc

   * CyAsHalFree

*/

EXTERN void

CyAsHalCBFree(

    void *                              ptr             /* Pointer to the memory block to be freed */

    ) ;

/* Summary

   This function sets a block of memory to a specific value

   Description

   This function is the HAL layer equivalent of the memset() function.

   Returns

   None

*/

EXTERN void

CyAsMemSet(

    void *				ptr,		/* A pointer to a block of memory to set */

    uint8_t				value,		/* The value to set the memory to */

    uint32_t				cnt		/* The number of bytes to set */

    ) ;

/* Summary

   This function creates or initializes a sleep channel

   Description

   This function creates or initializes a sleep channel.  The sleep channel defined using

   the HAL data structure CyAsHalSleepChannel.

   Returns

   CyTrue is the initialization was sucessful, and CyFalse otherwise

   See Also

   * CyAsHalSleepChannel

   * CyAsHalDestroySleepChannel

   * CyAsHalSleepOn

   * CyAsHalWake

*/

EXTERN CyBool

CyAsHalCreateSleepChannel(

	CyAsHalSleepChannel		*chan		/* Pointer to the sleep channel to create/initialize */

	) ;

/* Summary

   This function destroys an existing sleep channel

   Description

   This function destroys an existing sleep channel.  The sleep channel is of type

   CyAsHalSleepChannel.