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, 800 insertions, 0 deletions
diff --git a/drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h b/drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h new file mode 100644 index 0000000..28136ad --- /dev/null +++ b/drivers/staging/westbridge/astoria/include/linux/westbridge/cyashaldoc.h @@ -0,0 +1,800 @@ +/* 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 |
