--- /dev/null
+/* Cypress West Bridge API header file (cyashaldoc.h)
+## ===========================
+## Copyright (C) 2010 Cypress Semiconductor
+##
+## This program is free software; you can redistribute it and/or
+## modify it under the terms of the GNU General Public License
+## as published by the Free Software Foundation; either version 2
+## of the License, or (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program; if not, write to the Free Software
+## Foundation, Inc., 51 Franklin Street
+## Fifth Floor, Boston, MA 02110-1301, USA.
+## ===========================
+*/
+
+#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 cy_as_hal_sleep_channel {
+ /* This structure is filled in with OS specific information
+ to implementat a sleep channel */
+ int m_channel;
+} cy_as_hal_sleep_channel;
+
+/* 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
+cy_as_hal_write_register(
+/* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The address we are writing to */
+ uint16_t addr,
+ /* The value to write to the register */
+ uint16_t value
+ );
+
+/* 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
+cy_as_hal_read_register(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The address we are writing to */
+ uint16_t addr
+ );
+
+/* 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 on
+ packet and the HAL layer may need to divide the request
+ into multiple hardware DMA operations.
+
+ Returns
+ None
+
+ See Also
+ * CyAsHalDmaSetupRead
+ * CyAsHalDmaMaxRequestSize
+*/
+EXTERN void
+cy_as_hal_dma_setup_write(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The endpoint we are writing to */
+ cy_as_end_point_number_t ep,
+ /* The data to write via DMA */
+ void *buf_p,
+ /* The size of the data at buf_p */
+ uint32_t size,
+ /* The maximum amount of data that the endpoint
+ * can accept as one packet */
+ uint16_t maxsize
+ );
+
+/* 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
+cy_as_hal_dma_setup_read(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The endpoint we are reading from */
+ cy_as_end_point_number_t ep,
+ /* The buffer to read data into */
+ void *buf_p,
+ /* The amount of data to read */
+ uint32_t size,
+ /* The maximum amount of data that the endpoint
+ * can provide in one DMA operation */
+ uint16_t maxsize
+ );
+
+/* 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
+cy_as_hal_dma_cancel_request(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The endpoint we are reading from */
+ cy_as_end_point_number_t ep
+ );
+
+/* 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
+cy_as_hal_dma_register_callback(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The callback to call when a request has completed */
+ cy_as_hal_dma_complete_callback cb
+ );
+
+/* 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
+cy_as_hal_dma_max_request_size(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The endpoint of interest */
+ cy_as_end_point_number_t ep
+ );
+
+/* 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
+cy_as_hal_set_wakeup_pin(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* The desired state of the wakeup pin */
+ cy_bool state
+ );
+
+/* 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 cy_bool
+cy_as_hal_sync_device_clocks(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ );
+
+/* 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
+cy_as_hal_init_dev_registers(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag,
+ /* Indicates whether this is a wake-up from standby. */
+ cy_bool is_standby_wakeup
+ );
+
+/* 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
+cy_as_hal_read_regs_before_standby(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag
+ );
+
+/* 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
+cy_as_hal_restore_regs_after_standby(
+ /* The tag to ID a specific West Bridge device */
+ cy_as_hal_device_tag tag
+ );
+
+/*
+ * 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 *
+cy_as_hal_alloc(
+ /* The size of the memory block to allocate */
+ uint32_t size
+ );
+
+/* 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
+cy_as_hal_free(
+ /* Pointer to a memory block to free */
+ void *ptr
+ );
+
+/* 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 *
+cy_as_hal_c_b_alloc(
+ /* The size of the memory block to allocate */
+ uint32_t size
+ );
+
+/* 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
+cy_as_hal_c_b_free(
+ /* Pointer to the memory block to be freed */
+ void *ptr
+ );
+
+/* 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
+cy_as_mem_set(
+ /* A pointer to a block of memory to set */
+ void *ptr,
+ /* The value to set the memory to */
+ uint8_t value,
+ /* The number of bytes to set */
+ uint32_t cnt
+ );
+
+/* 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 cy_bool
+cy_as_hal_create_sleep_channel(
+ /* Pointer to the sleep channel to create/initialize */
+ cy_as_hal_sleep_channel *chan
+ );
+
+/* 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 cy_bool
+cy_as_hal_destroy_sleep_channel(
+ /* The sleep channel to destroy */
+ cy_as_hal_sleep_channel chan
+ );
+
+/* 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 cy_bool
+cy_as_hal_sleep_on(
+ /* The sleep channel to sleep on */
+ cy_as_hal_sleep_channel chan,
+ /* The maximum time to sleep in milli-seconds */
+ uint32_t ms
+ );
+
+/* 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 cy_bool
+cy_as_hal_wake(
+ /* The sleep channel to wake */
+ cy_as_hal_sleep_channel chan
+ );
+
+/* 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
+cy_as_hal_disable_interrupts();
+
+/* 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
+cy_as_hal_enable_interrupts(
+ /* Value returned by the previous CyAsHalDisableInterrupts call. */
+ uint32_t value
+ );
+
+/* 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
+cy_as_hal_sleep150(
+ );
+
+/* Summary
+ This function sleeps for the given number of milliseconds
+
+ Description
+ This function sleeps for at least the given number of milliseonds
+*/
+EXTERN void
+cy_as_hal_sleep(
+ 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
+cy_as_hal_assert(
+ /* The condition to evaluate */
+ cy_bool cond
+ );
+
+/* 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
+cy_as_hal_print_message(
+ /* The message to print */
+ const char *fmt_p,
+ ... /* 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 cy_bool
+cy_as_hal_is_polling(
+ void);
+
+#endif
projects / mv-sheeva.git / blobdiff