diff -r b7e488c49d0d -r 117faf51deac omap3530/beagle_drivers/wb/api/include/cyashaldoc.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/omap3530/beagle_drivers/wb/api/include/cyashaldoc.h	Wed Mar 03 13:10:32 2010 +0000
@@ -0,0 +1,687 @@
+/* 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.
+
+   Returns
+   CyTrue if the channel was destroyed, and CyFalse otherwise
+
+   See Also
+   * CyAsHalSleepChannel
+   * CyAsHalCreateSleepChannel
+   * CyAsHalSleepOn
+   * CyAsHalWake
+*/
+EXTERN CyBool
+CyAsHalDestroySleepChannel(
+	CyAsHalSleepChannel		chan		/* The sleep channel to destroy */
+	) ;
+
+/* Summary
+   This function causes the calling process or thread to sleep until CyAsHalWake() is called
+
+   Description
+   This function causes the calling process or threadvto sleep.  When CyAsHalWake() is called 
+   on the same sleep channel, this processes or thread is then wakened and allowed to run
+
+   Returns
+   CyTrue if the thread or process is asleep, and CyFalse otherwise
+
+   See Also
+   * CyAsHalSleepChannel
+   * CyAsHalWake
+*/
+EXTERN CyBool
+CyAsHalSleepOn(
+	CyAsHalSleepChannel		chan,		/* The sleep channel to sleep on */
+	uint32_t				ms			/* The maximum time to sleep in milli-seconds */
+	) ;
+
+/* Summary
+   This function casues the process or thread sleeping on the given sleep channel to wake
+
+   Description
+   This function causes the process or thread sleeping on the given sleep channel to wake.  The
+   channel
+
+   Returns
+   CyTrue if the thread or process is awake, and CyFalse otherwise
+
+   See Also
+   * CyAsHalSleepChannel
+   * CyAsHalSleepOn
+*/
+EXTERN CyBool
+CyAsHalWake(
+	CyAsHalSleepChannel		chan		/* The sleep channel to wake */
+	) ;
+
+/* Summary
+   This function disables interrupts, insuring that short bursts of code can be run without danger of interrupt
+   handlers running.
+
+   Description
+   There are cases within the API when lists must be manipulated by both the API and the associated
+   interrupt handlers.  In these cases, interrupts must be disabled to insure the integrity of the list during the 
+   modification.  This function is used to disable interrupts during the short intervals where these lists are being
+   changed.
+
+   The HAL must have the ability to nest calls to CyAsHalDisableInterrupts and CyAsHalEnableInterrupts.
+
+   Returns
+   Any interrupt related state value which will be passed back into the subsequent CyAsHalEnableInterrupts call.
+
+   See Also
+   * CyAsHalEnableInterrupts
+*/
+EXTERN uint32_t
+CyAsHalDisableInterrupts() ;
+
+/* Summary
+   This function re-enables interrupts after a critical section of code in the API has been completed.
+
+   Description
+   There are cases within the API when lists must be manipulated by both the API and the associated
+   interrupt handlers.  In these cases, interrupts must be disabled to insure the integrity of the list during the 
+   modification.  This function is used to enable interrupts after the short intervals where these lists are being
+   changed.
+
+   See Also
+   * CyAsHalDisableInterrupts
+*/
+EXTERN void
+CyAsHalEnableInterrupts(
+        uint32_t value                          /* Value returned by the previous CyAsHalDisableInterrupts call. */
+        ) ;
+
+/* Summary
+   This function sleeps for 150 ns.
+
+   Description
+   This function sleeps for 150 ns before allowing the calling function to continue.  This function is used for a
+   specific purpose and the sleep required is at least 150 ns.
+*/
+EXTERN void
+CyAsHalSleep150(
+        ) ;
+
+/* Summary
+   This function sleeps for the given number of milliseconds
+
+   Description
+   This function sleeps for at least the given number of milliseonds
+*/
+EXTERN void
+CyAsHalSleep(
+        uint32_t ms
+        ) ;
+
+/* Summary
+   This function asserts when the condition evaluates to zero
+
+   Description
+   Within the API there are conditions which are checked to insure the integrity of the code.  These conditions are
+   checked only within a DEBUG build.  This function is used to check the condition and if the result evaluates to
+   zero, it should be considered a fatal error that should be reported to Cypress.
+*/
+EXTERN void
+CyAsHalAssert(
+	CyBool					cond		/* The condition to evaluate */
+	) ;
+
+/* Summary
+   This function prints a message from the API to a human readable device
+
+   Description
+   There are places within the West Bridge API where printing a message is useful to the debug process.  This function
+   provides the mechanism to print a message.
+
+   Returns
+   NONE
+*/
+EXTERN void
+CyAsHalPrintMessage(
+	const char *			fmt_p,		/* The message to print */
+	...						/* Variable arguments */
+	) ;
+
+/* Summary
+   This function reports whether the HAL implementation uses polling to service
+   data coming from the West Bridge.
+
+   Description
+   This function reports whether the HAL implementation uses polling to service
+   data coming from the West Bridge.
+
+   Returns
+   CyTrue if the HAL polls the West Bridge Interrupt Status registers to complete operations,
+   CyFalse if the HAL is interrupt driven.
+ */
+EXTERN CyBool
+CyAsHalIsPolling (
+        void) ;
+
+#endif