/* * Copyright (c) 2011 Intel Corporation. All Rights Reserved. * Copyright (c) Imagination Technologies Limited, UK * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the * "Software"), to deal in the Software without restriction, including * without limitation the rights to use, copy, modify, merge, publish, * distribute, sub license, and/or sell copies of the Software, and to * permit persons to whom the Software is furnished to do so, subject to * the following conditions: * * The above copyright notice and this permission notice (including the * next paragraph) shall be included in all copies or substantial portions * of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ /*! ****************************************************************************** @file : dma_api.h @brief @date 02/11/2005 \nDescription:\n This file contains header file for the MTX DMAC API. The MTX DMAC API can operate synchronously or asynchronously. In synchronous case, the API uses an internal callback function to detect state transitions and the SEMA API to block whilst waiting for the transfer to complete. In the asynchronous case, the caller is responsible for detecting and handling the state transitions and synchronising with other processes/processing. \nPlatform:\n MSVDX/MTX ******************************************************************************/ /* ****************************************************************************** Modifications :- $Log: dma_api.h $ --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- --- Revision Logs Removed --- *****************************************************************************/ #if !defined (__DMA_API_H__) #define __DMA_API_H__ #include #include "msvdx_dmac_regs_io2.h" #include "msvdx_dmac_linked_list.h" #if (__cplusplus) extern "C" { #endif /*! ****************************************************************************** This type defines the DMAC status ******************************************************************************/ typedef enum { DMA_STATUS_IDLE, //!< The DMAC is idle. DMA_STATUS_BUSY, //!< The DMAC is busy - a DMA is in progress. DMA_STATUS_COMPLETE, /*!< The DMAC operation has completed - return by DMA_GetStatus()once before the DMAC returns to #DMA_STATUS_IDLE. */ DMA_STATUS_TIMEOUT, /*!< The DMAC operation has timed-out - return by DMA_GetStatus()once before the DMAC returns to #DMA_STATUS_IDLE. */ } DMA_eStatus; /*! ****************************************************************************** This type defines the DMA channel Ids ******************************************************************************/ typedef enum { DMA_CHANNEL_MTX = 0x0, //!< DMA channel for MTX DMA_CHANNEL_RESERVED, //!< DMA channel 1 is reserved for VEC use DMA_CHANNEL_SR1, //!< DMA channel for 1st shift register DMA_CHANNEL_SR2, //!< DMA channel for 2nd shift register DMA_CHANNEL_SR3, //!< DMA channel for 3rd shift register DMA_CHANNEL_SR4, //!< DMA channel for 4th shift register } DMA_eChannelId; /*! ****************************************************************************** Used with DMA_SyncAction() and DMA_AsyncAction() to indicate whether the peripheral is the mtx or not. ******************************************************************************/ enum { DMA_PERIPH_IS_NOT_MTX = 0, //!< The peripheral is not the mtx. DMA_PERIPH_IS_MTX = 1, //!< The peripheral is the mtx. }; /*! ****************************************************************************** This type defines the byte swap settings. ******************************************************************************/ typedef enum { DMA_BSWAP_NO_SWAP = 0x0, //!< No byte swapping will be performed. DMA_BSWAP_REVERSE = 0x1, //!< Byte order will be reversed. } DMA_eBSwap; /*! ****************************************************************************** This type defines the peripheral width settings ******************************************************************************/ typedef enum { DMA_PWIDTH_32_BIT = 0x0, //!< Peripheral width 32-bit. DMA_PWIDTH_16_BIT = 0x1, //!< Peripheral width 16-bit. DMA_PWIDTH_8_BIT = 0x2, //!< Peripheral width 8-bit. } DMA_ePW; /*! ****************************************************************************** This type defines the direction of the DMA transfer ******************************************************************************/ typedef enum { DMA_DIR_MEM_TO_PERIPH = 0x0, //!< Data from memory to peripheral. DMA_DIR_PERIPH_TO_MEM = 0x1, //!< Data from peripheral to memory. } DMA_eDir; /*! ****************************************************************************** This type defines whether the peripheral address is to be incremented ******************************************************************************/ typedef enum { DMA_PERIPH_INCR_ON = 0x1, //!< Peripheral address will be incremented DMA_PERIPH_INCR_OFF = 0x0, //!< Peripheral address will not be incremented } DMA_ePeriphIncr; /*! ****************************************************************************** This type defines how much the peripheral address is incremented by ******************************************************************************/ typedef enum { DMA_PERIPH_INCR_1 = 0x2, //!< Increment peripheral address by 1 DMA_PERIPH_INCR_2 = 0x1, //!< Increment peripheral address by 2 DMA_PERIPH_INCR_4 = 0x0, //!< Increment peripheral address by 4 } DMA_ePeriphIncrSize; /*! ****************************************************************************** This type defines whether the 2d mode is enabled or disabled ******************************************************************************/ typedef enum { DMA_MODE_2D_ON = 0x1, //!< the 2d mode will be used DMA_MODE_2D_OFF = 0x0, //!< the 2d mode will not be used } DMA_eMode2D; /*! ****************************************************************************** @Function DMA_LL_SET_WD0 @Description Set word 0 in a dmac linked list entry. @Input pList : pointer to start of linked list entry @Input BSWAP : big/little endian byte swap (see DMA_eBSwap). @Input DIR : transfer direction (see DMA_eDir). @Input PW : peripheral width (see DMA_ePW). @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD0(pList, BSWAP, DIR, PW) \ do{ \ MEMIO_WRITE_FIELD(pList, DMAC_LL_BSWAP, BSWAP); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_DIR, DIR); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_PW, PW); \ }while(0) /*! ****************************************************************************** @Function DMA_LL_SET_WD1 @Description Set word 1 in a dmac linked list entry. @Input pList : pointer to start of linked list entry @Input INCR : whether to increment the peripeheral address (see DMA_ePeriphIncr) @Input PI : how much to increment the peripheral address by (see DMA_ePeriphIncrSize) @Input LEN : length of transfer in peripheral width units @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD1(pList, INCR, PI, LEN) \ do { \ MEMIO_WRITE_FIELD(pList, DMAC_LL_PI, PI); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_INCR, INCR); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_LEN, LEN); \ }while(0) /*! ****************************************************************************** @Function DMA_LL_SET_WD2 @Description Set word 2 in a dmac linked list entry. @Input pList : pointer to start of linked list entry @Input PERI_ADDR : the perihperal address to transfer to/from @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD2(pList, PERI_ADDR) \ do { \ MEMIO_WRITE_FIELD(pList, DMAC_LL_ADDR, PERI_ADDR); \ }while(0) /*! ****************************************************************************** @Function DMA_LL_SET_WD3 @Description Set word 3 in a dmac linked list entry. @Input pList : pointer to start of linked list entry @Input ACC_DEL : access delay (see DMA_eAccDel) @Input BURST : burst size (see DMA_eBurst) @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD3(pList, ACC_DEL, BURST , EXTSA ) \ do { \ MEMIO_WRITE_FIELD(pList, DMAC_LL_ACC_DEL, ACC_DEL); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_BURST, BURST); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_EXT_SA, EXTSA); \ }while(0) /*! ****************************************************************************** @Function DMA_LL_SET_WD4 @Description Set word 4 in a dmac linked list entry. @Input pList : pointer to start of linked list entry @Input MODE_2D : enable/disable 2d mode (see DMA_eMode2D) @Input REP_COUNT : repeat count (the number of rows transferred) @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD4(pList, MODE_2D, REP_COUNT) \ do { \ MEMIO_WRITE_FIELD(pList, DMAC_LL_MODE_2D, MODE_2D); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_REP_COUNT, REP_COUNT); \ } while(0) /*! ****************************************************************************** @Function DMA_LL_SET_WD5 @Description Set word 5 in a dmac linked list entry. @Input pList : pointer to start of linked list entry @Input LINE_ADD_OFF : number of bytes from the end of one row to the start of the next row (only applicable when using 2D transfer mode) @Input ROW_LENGTH : number of bytes per row (only applicable when using 2D transfer mode) @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD5(pList, LINE_ADD_OFF, ROW_LENGTH) \ do{ \ MEMIO_WRITE_FIELD(pList, DMAC_LL_LINE_ADD_OFF, LINE_ADD_OFF); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_ROW_LENGTH, ROW_LENGTH); \ }while(0) /*! ****************************************************************************** @Function DMA_LL_SET_WD6 @Description Set word 6 in a dmac linked list entry. @Input pList : pointer to start of linked list entry @Input SA : the host memory address to transfer to/from @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD6(pList, SA) \ do{ \ MEMIO_WRITE_FIELD(pList, DMAC_LL_SA, SA); \ }while(0) /*! ****************************************************************************** @Function DMA_LL_SET_WD7 @Description Set word 7 in a dmac linked list entry. @Input pList: pointer to start of linked list entry @Input LISTPTR: pointer to next linked list entry If the linked list entry is in MTX memory (eListLocation == DMA_LIST_IS_IN_MTX_MEM) then LISTPTR is a pointer to the start of the next linked list entry. If the linked list entry is in HOST memory (eListLocation == DMA_LIST_IS_IN_SYS_MEM) then LISTPTR is a pointer to the start of the next linked list entry, but right shifted by 4 bits (i.e. ptr >> 4). If this is the last entry in the linked list sequence then LISTPTR must be set to NULL. @Return nothing ******************************************************************************/ #define DMA_LL_SET_WD7(pList, LISTPTR) \ do { \ MEMIO_WRITE_FIELD(pList, DMAC_LL_LISTPTR, LISTPTR); \ MEMIO_WRITE_FIELD(pList, DMAC_LL_LIST_FIN, (LISTPTR) ? 0 : 1); \ }while(0) /*! ****************************************************************************** @Function DMA_VALUE_COUNT @Description This MACRO is used to aid the generation of the ui32Count member of the DMA_sParams structure required by DMA_SyncAction() and DMA_AsyncAction(). If this is not suitable for a given application then the programmer is free to fill in the fields in any way they see fit. @Input BSWAP : Big/little endian byte swap (see DMA_eBSwap). @Input PW : The width of the peripheral DMA register (see DMA_ePW). @Input DIR : The direction of the transfer (see DMA_eDir). @Input PERIPH_INCR : How much to increment the peripheral address by (see DMA_ePeriphIncr). @Input COUNT : The length of the transfer in transfer units. @Return img_uint32 : The value of the generated word. ******************************************************************************/ #define DMA_VALUE_COUNT(BSWAP,PW,DIR,PERIPH_INCR,COUNT) \ \ (((BSWAP) & DMAC_DMAC_COUNT_BSWAP_LSBMASK) << DMAC_DMAC_COUNT_BSWAP_SHIFT) | \ (((PW) & DMAC_DMAC_COUNT_PW_LSBMASK) << DMAC_DMAC_COUNT_PW_SHIFT) | \ (((DIR) & DMAC_DMAC_COUNT_DIR_LSBMASK) << DMAC_DMAC_COUNT_DIR_SHIFT) | \ (((PERIPH_INCR) & DMAC_DMAC_COUNT_PI_LSBMASK) << DMAC_DMAC_COUNT_PI_SHIFT) | \ (((COUNT) & DMAC_DMAC_COUNT_CNT_LSBMASK) << DMAC_DMAC_COUNT_CNT_SHIFT) /*! ****************************************************************************** This type defines the access delay settings. ******************************************************************************/ typedef enum { DMA_ACC_DEL_0 = 0x0, //!< Access delay zero clock cycles DMA_ACC_DEL_256 = 0x1, //!< Access delay 256 clock cycles DMA_ACC_DEL_512 = 0x2, //!< Access delay 512 clock cycles DMA_ACC_DEL_768 = 0x3, //!< Access delay 768 clock cycles DMA_ACC_DEL_1024 = 0x4, //!< Access delay 1024 clock cycles DMA_ACC_DEL_1280 = 0x5, //!< Access delay 1280 clock cycles DMA_ACC_DEL_1536 = 0x6, //!< Access delay 1536 clock cycles DMA_ACC_DEL_1792 = 0x7, //!< Access delay 1792 clock cycles } DMA_eAccDel; /*! ****************************************************************************** This type defines whether the peripheral address is static or auto-incremented. ******************************************************************************/ typedef enum { DMA_INCR_OFF = 0, //!< Static peripheral address. DMA_INCR_ON = 1 //!< Incrementing peripheral address. } DMA_eIncr; /*! ****************************************************************************** This type defines the burst size setting. ******************************************************************************/ typedef enum { DMA_BURST_0 = 0x0, //!< burst size of 0 DMA_BURST_1 = 0x1, //!< burst size of 1 DMA_BURST_2 = 0x2, //!< burst size of 2 DMA_BURST_3 = 0x3, //!< burst size of 3 DMA_BURST_4 = 0x4, //!< burst size of 4 DMA_BURST_5 = 0x5, //!< burst size of 5 DMA_BURST_6 = 0x6, //!< burst size of 6 DMA_BURST_7 = 0x7, //!< burst size of 7 } DMA_eBurst; /*! ****************************************************************************** @Function DMA_VALUE_PERIPH_PARAM @Description This MACRO is used to aid the generation of the ui32PeripheralParam member of the DMA_sParams structure required by DMA_SyncAction() and DMA_AsyncAction(). If this is not suitable for a given application then the programmer is free to fill in the fields in any way they see fit. @Input ACC_DEL: The access delay (see DMA_eAccDel). @Input INCR: Whether the peripheral address is incremented (see DMA_eIncr). @Input BURST: The burst size. This should correspond to the amount of data that the peripheral will either be able to supply or accept from its FIFO (see DMA_eBurst). @Return img_uint32: The value of the generated word. ******************************************************************************/ #define DMA_VALUE_PERIPH_PARAM(ACC_DEL,INCR,BURST) \ \ (((ACC_DEL) & DMAC_DMAC_PERIPH_ACC_DEL_LSBMASK) << DMAC_DMAC_PERIPH_ACC_DEL_SHIFT) | \ (((INCR) & DMAC_DMAC_PERIPH_INCR_LSBMASK) << DMAC_DMAC_PERIPH_INCR_SHIFT) | \ (((BURST) & DMAC_DMAC_PERIPH_BURST_LSBMASK) << DMAC_DMAC_PERIPH_BURST_SHIFT) /*! ****************************************************************************** Used to describe the location of the linked list structure ******************************************************************************/ typedef enum { DMA_LIST_IS_IN_MTX_MEM, DMA_LIST_IS_IN_SYS_MEM, } DMA_LIST_LOCATION; /*! ****************************************************************************** DMAC linked list structure ******************************************************************************/ typedef struct { IMG_UINT32 ui32Word_0; //!< Word 0 of the linked list (see DMA_LL_SET_WD0). IMG_UINT32 ui32Word_1; //!< Word 1 of the linked list (see DMA_LL_SET_WD1). IMG_UINT32 ui32Word_2; //!< Word 2 of the linked list (see DMA_LL_SET_WD2). IMG_UINT32 ui32Word_3; //!< Word 3 of the linked list (see DMA_LL_SET_WD3). IMG_UINT32 ui32Word_4; //!< Word 4 of the linked list (see DMA_LL_SET_WD4). IMG_UINT32 ui32Word_5; //!< Word 5 of the linked list (see DMA_LL_SET_WD5). IMG_UINT32 ui32Word_6; //!< Word 6 of the linked list (see DMA_LL_SET_WD6). IMG_UINT32 ui32Word_7; //!< Word 7 of the linked list (see DMA_LL_SET_WD7). } DMA_sLinkedList; /*! ****************************************************************************** DMAC Parameter structure ******************************************************************************/ typedef struct { IMG_UINT32 ui32PerHold; //!< peripheral hold register (see PER_HOLD register in TRM) DMA_LIST_LOCATION eListLocation; //!< is the linked list in mtx memory or system memory DMA_sLinkedList * psDmaLinkedList; //!< pointer to first element in the linked list IMG_UINT32 ui32Ext_sa; } DMA_sParams; /*! ****************************************************************************** @Function DMA_Initialise @Description This function initialises the DMAC. Only has effect on the first call, second and subsequent calls are ignored. @Input eChannel : The channel to initialise. @Return None. ******************************************************************************/ extern IMG_VOID DMA_Initialise(DMA_eChannelId eChannel); /*! ****************************************************************************** @Function DMA_Reset @Description This function resets the DMAC, cancels any pending DMAC operation and return the DMAC to the idle state - #DMA_STATUS_IDLE. @Input eChannel : The channel to reset. @Return None. ******************************************************************************/ extern IMG_VOID DMA_Reset(DMA_eChannelId eChannel); /*! ****************************************************************************** @Function DMA_SyncAction @Description This function is used to initiate a synchronous (blocking) DMAC tranfer. An internal callback function is registered using DMA_RegisterStatusCallback() to detect and act upon status transitions. The DMAC driver also uses the SEMA API, SEMA_ID_B to block whilst waiting for the DMAC transfer to complete. The callback function will set the semaphore when the NOTE: The DMAC must be in the idle state - #DMA_STATUS_IDLE - when the transfer is initiated. @Input eChannel : The channel to use. @Input psParams : A pointer to a #DMA_sParams structure set with the required DMAC setup. @Input bMtx : If true then the peripheral address specifies an offset in MTX memory @Return DMA_eStatus : The completion status - #DMA_STATUS_COMPLETE or #DMA_STATUS_TIMEOUT. ******************************************************************************/ extern DMA_eStatus DMA_SyncAction( DMA_eChannelId eChannel, DMA_sParams * psParams, IMG_BOOL bMtx ); /*! ****************************************************************************** @Function DMA_AsyncAction @Description This function is used to initiate an asynchronous (non-blocking) DMAC tranfer. NOTE: The DMAC must be in the idle state - #DMA_STATUS_IDLE - when the transfer is initiated. @Input eChannel : The channel to use. @Input psDmacLinkedList : A pointer to a #DMA_sLinkedList structure set with the required DMAC setup. @Input bPeriphIsMtx : If true then the peripheral address specifies an offset in MTX memory. NOTE: If eListLocation is DMA_LIST_IS_IN_SYS_MEM and bPeriphIsMtx is IMG_TRUE the linked list can only contain a single entry. NOTE: If eListLocation is DMA_LIST_IS_IN_MTX_MEM then bPeriphIsMtx applies to all entries in the linked list (i.e. they all use the mtx as the peripheral, or none of them use the mtx as the peripheral). @Return None. ******************************************************************************/ extern IMG_VOID DMA_AsyncAction( DMA_eChannelId eChannel, DMA_sParams * psParams, IMG_BOOL bPeriphIsMtx ); /*! ****************************************************************************** @Function DMA_WaitForTransfer @Description This function waits for the current transfer to complete or timeout. @Input eChannel : The channel to wait use. @Return DMA_eStatus : DMA_STATUS_COMPLETE when transfer has completed or DMA_STATUS_IDLE if there wasn't an active transfer in progress to wait for. ******************************************************************************/ extern DMA_eStatus DMA_WaitForTransfer(DMA_eChannelId eChannel); /*! ****************************************************************************** @Function DMA_GetStatus @Description This function returns the status of the DMAC. @Input eChannel : The channel to get the status of. @Return DMA_eStatus : The status of the DMAC. ******************************************************************************/ extern DMA_eStatus DMA_GetStatus(DMA_eChannelId eChannel); /*! ****************************************************************************** @Function DMA_pfnStatusCallback @Description This is the prototype for a status callback functions. @Input eChannel : The channel that the status change is being reported on. @Input DMA_eStatus : The "new" state of the DMAC. @Return None. ******************************************************************************/ typedef IMG_VOID(*DMA_pfnStatusCallback)( DMA_eChannelId eChannel, DMA_eStatus eStatus ); /*! ****************************************************************************** @Function DMA_RegisterStatusCallback @Description This function is used to register a status callback function. The caller provides the address of a function that will be called when a change in the status occurs - see #DMA_eStatus. NOTE: This can happen asynchronously (at interrupt level) on a #DMA_STATUS_COMPLETE or #DMA_STATUS_TIMEOUT - or synchronously when DMA_Action() is called and the state changes to #DMA_STATUS_BUSY or when DMA_GetStatus() or DMA_Reset() are called and the state returns to #DMA_STATUS_IDLE. NOTE: Only one callback function can be registered with the API. The callback function is persistent and is not removed by subsequent calls to DMA_Initialise() or DMA_Reset(). NOTE: The function asserts if a callback function has already been set. @Input eChannel : The channel that the status change is being reported on. @Input pfnStatusCallback : A pointer to a status callback function. @Return None. ******************************************************************************/ extern IMG_VOID DMA_RegisterStatusCallback( DMA_eChannelId eChannel, DMA_pfnStatusCallback pfnStatusCallback ); #if (__cplusplus) } #endif #endif /* __DMA_API_H__ */