diff options
Diffstat (limited to 'drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h')
| -rw-r--r-- | drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h | 800 |
1 files changed, 0 insertions, 800 deletions
diff --git a/drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h b/drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h deleted file mode 100644 index 5bcbe9bf2f5d..000000000000 --- a/drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h +++ /dev/null @@ -1,800 +0,0 @@ -/* 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 successful, 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 |