/* Customer ID=11656; Build=0x5f626; Copyright (c) 2005-2014 by Cadence Design Systems, Inc. ALL RIGHTS RESERVED.
* These coded instructions, statements, and computer programs are the
* copyrighted works and confidential proprietary information of
* Cadence Design Systems, Inc. They may not be modified, copied, reproduced,
* distributed, or disclosed to third parties in any manner, medium, or form,
* in whole or in part, without the prior written consent of Cadence Design
* Systems Inc.
*/
#ifndef __UDMA_H__
#define __UDMA_H__
#include <stdint.h>
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Size of the uDMA descriptor */
#define UDMA_DESC_STRUCT_SIZE 32
/* Request attribute is a bit vector passed to the udma functions - udma_copy,
* udma_2d_copy, udma_add_descs.
* Bit 0 : 1 - trigger an interrupt when done, else do nothing
* Bit 1 : 0 - retry the failed request; abort after programmer specified
* number of retries. Defaults to abort with no retries.
* 1 - abort the failed request (after retries) and all pending requests
*/
#define UDMA_DONE_INTERRUPT 0x1
#define UDMA_ERROR_ABORT 0x0
#define UDMA_ERROR_ABORT_ALL 0x2
/* Enum representing various udma error conditions, udma status, and
* return values
*/
typedef enum {
UDMA_OK = 0,
UDMA_ERROR_QUEUE_FULL = 1,
UDMA_ERROR_BAD_DESC = 2,
UDMA_ERROR_DRAM_CROSSING = 3,
UDMA_ERROR_PIF_ADDR_BUS = 4,
UDMA_ERROR_PIF_DATA_BUS = 5,
UDMA_REQ_PENDING = 6,
UDMA_REQ_DONE = 7,
UDMA_ERROR_BAD_REQUEST = 8,
UDMA_ERROR_INVALID_ARG = 11,
UDMA_ERROR_INIT = 12,
UDMA_ERROR_INTERNAL = -1
} udma_status_t;
#ifndef __UDMA_INTERNAL_H__
/* Opaque structure describing a uDMA descriptor */
struct udma_desc_struct {
char _[UDMA_DESC_STRUCT_SIZE];
} __attribute__ ((aligned (UDMA_DESC_STRUCT_SIZE)));
#endif
typedef struct udma_desc_struct udma_desc_t;
/* Initialize the udma control structure, the uDMA registers with
* the descriptor queue addresses, and the uDMA sync and error interrupt
* handler. This function needs to be invoked prior to using the uDMA.
*
* xmp_udma_sync_intr : Processor interrupt number to flag udma done
* xmp_udma_error_intr : Processor interrupt number to flag udma error
*
* Returns UDMA_ERROR_INIT if there was an error during initialization else
* returns UDMA_OK.
*/
extern udma_status_t
udma_init(uint32_t xmp_udma_sync_intr, uint32_t xmp_udma_error_intr);
/* Performs a copy of a linear block of size bytes from the src
* to the dest address. If the call returns UDMA_OK, status is set to
* UDMA_REQ_PENDING or UDMA_REQ_DONE. If there is a dma error, the error code,
* which could be one of UDMA_ERROR_BAD_DESC, UDMA_ERROR_DRAM_CROSSING,
* UDMA_ERROR_PIF_ADDR_BUS, UDMA_ERROR_PIF_DATA_BUS is returned in the status.
* Status is set to UDMA_REQ_DONE if the dma completes normally.
* On completion, the callback function is invoked with the callback_data
* and status as parameters. Note, the callback is always invoked even if
* there is a dma error.
*
* src : src address of the copy
* dest : dest address of the copy
* size : number of bytes to copy
* callback_data : optional data to be passed to callback_func
* callback_func : optional callback after copy is done
* request_attr : attribute defining how to process this request
* (see description of the request attribute in top of udma.h)
* status : track status of the copy; this gets also passed
* as the second argument to the callback_func
*
* Returns UDMA_ERROR_QUEUE_FULL if no more requests can be added, else
* returns UDMA_OK.
*/
extern udma_status_t
udma_copy(void *dest,
void *src,
size_t size,
void *callback_data,
void (*callback_func)(void *, udma_status_t *status),
uint32_t request_attr,
udma_status_t *status);
/* Performs a copy of a 2D block of data from the src to the dest
* address. If the call returns UDMA_OK, status is set to UDMA_REQ_PENDING or
* UDMA_REQ_DONE. If there is a dma error, the error code,
* which could be one of UDMA_ERROR_BAD_DESC, UDMA_ERROR_DRAM_CROSSING,
* UDMA_ERROR_PIF_ADDR_BUS, UDMA_ERROR_PIF_DATA_BUS is returned in the status.
* Status is set to UDMA_REQ_DONE if the dma completes normally.
* On completion, the callback function is invoked with the callback_data
* and status as parameters. Note, the callback is always invoked even if
* there is a dma error.
*
* src : src address of the copy
* dest : dest address of the copy
* row_size : number of bytes per row to copy
* num_rows : number of rows to copy
* src_pitch : src pitch
* dest_pitch : dest pitch
* callback_data : optional data to be passed to callback_func
* callback_func : optional callback after copy is done
* request_attr : attribute defining how to process this request
* (see description of the request attribute in top of udma.h)
* status : track status of the copy; this gets also passed
* as the second argument to the callback_func
*
* Returns UDMA_ERROR_QUEUE_FULL if no more requests can be added, else
* returns UDMA_OK.
*/
extern udma_status_t
udma_2d_copy(void *dest,
void *src,
size_t row_size,
uint32_t num_rows,
uint32_t src_pitch,
uint32_t dest_pitch,
void *callback_data,
void (*callback_func)(void *, udma_status_t *status),
uint32_t request_attr,
udma_status_t *status);
/* Process requests that are done. Any callbacks associated
* with the completed requests gets invoked. If there are any errors,
* the error request is (and any pending request based on the request attribute)
* cancelled and the error code is returned in the status associated with
* all such cancelled requests. Callbacks associated with the cancelled
* requests are also invoked. If all requests terminate normally, the status
* of the completed requests are set to UDMA_REQ_DONE.
*
* Returns void
*/
extern void
udma_process_requests();
/* Sets the udma max PIF block size
*
* max_block_size : max block size to be set
*
* Returns UDMA_ERROR_INVALID_ARG if block_size is > 3, else returns UDMA_OK
*/
udma_status_t
udma_set_max_block_size(uint32_t block_size);
/* Sets the udma max outstanding PIF requests
*
* max_outstanding : max outstanding PIF requests
*
* Returns UDMA_ERROR_INVALID_ARG if max_outstanding is not between 1 and 16
* else returns UDMA_OK
*/
udma_status_t
udma_set_max_outstanding(uint32_t max_outstanding);
/* Initialize a uDMA descriptor using the copy parameters. The descriptor
* is then queued separately using udma_add_desc
*
* src : src address of the copy
* dest : dest address of the copy
* row_size : number of bytes per row to copy
* num_rows : number of rows to copy
* src_pitch : src pitch
* dest_pitch : dest pitch
* notify_with_interrupt : If 1, interrupt when dma is done with this descriptor
* if 0, do nothing, else undefined
*
* Returns void
*/
extern void
udma_set_desc(void *src,
void *dest,
size_t row_size,
uint32_t num_rows,
uint32_t src_pitch,
uint32_t dest_pitch,
uint32_t notify_with_interrupt,
udma_desc_t *desc);
/* Add multiple uDMA descriptors to the descriptor queue. If the call returns
* UDMA_OK, the status is set to UDMA_REQ_PENDING or UDMA_REQ_DONE.
* If there is a dma error, the error code, which could be one of
* UDMA_ERROR_BAD_DESC, UDMA_ERROR_DRAM_CROSSING, UDMA_ERROR_PIF_ADDR_BUS,
* UDMA_ERROR_PIF_DATA_BUS is returned in the status. Status is set
* to UDMA_REQ_DONE, if the dma completes normally.
* On completion, the callback function is invoked with the callback_data
* and status as parameters. Note, the callback is always invoked even if
* there is a dma error.
*
* desc : descriptors to be added
* num_desc : number of descriptors to be added
* callback_data : optional data to be passed to callback_func
* callback_func : optional callback after copy is done
* request_attr : attribute defining how to process this request
* (see description of the request attribute in top of udma.h)
* Note, bit 0 (for enabling interrupt) is ignored in this call.
* To interrupt on dma completion, set the
* notify_with_interrupt parameter when creating descriptors
* using udma_set_desc.
* status : track status of the copy; this gets also passed
* as the second argument to the callback_func
*
* Returns UDMA_ERROR_QUEUE_FULL if no more descriptors can be added,
* UDMA_ERROR_INVALID_ARG if num_descs == 0, else return UDMA_OK
*/
udma_status_t
udma_add_descs(udma_desc_t *descs,
uint32_t num_descs,
void *callback_data,
void (*callback_func)(void *, udma_status_t *status),
uint32_t request_attr,
udma_status_t *status);
/* Wait for udma copy request to complete. Could spin wait or goto waiti
* based on the sleep_wait parameter. Once the request is done, the callback
* associated with this request and any prior completed requests are handled.
* Error code, if any, is returned in the status s, else s is set to
* UDMA_REQ_DONE.
*
* s : status to wait for
* sleep_wait : sleep wait if true, else spin waits
*
* Returns void
*/
extern void
udma_wait_request(volatile udma_status_t *s, uint32_t sleep_wait);
/* Inlined function to set the src, dest address of the descriptor
*
* src : src address of the uDMA
* dest : dest address of the uDMA
* desc : descriptor to be modified
*
* Returns void
*/
void static inline
udma_set_desc_addrs(void *src, void *dest, udma_desc_t *desc) {
uint32_t *d = (uint32_t *)desc;
*d = (uintptr_t)src;
*(d+1) = (uintptr_t)dest;
}
/* Sets the number of retries for a failed dma request
*
* max_retries : max number of retries
*
* Sets the max number of retries for a failed dma request. The default is 0,
* i.e, no retries
*/
void
udma_set_max_retries(uint32_t max_retries);
#ifdef __cplusplus
}
#endif
#endif /* __UDMA_H__ */