source: rtems/c/src/lib/libbsp/powerpc/gen5200/bestcomm/bestcomm_api.h @ ca680bc5

#ifndef __BESTCOMM_API_H
#define __BESTCOMM_API_H 1

/******************************************************************************
*
* Copyright (c) 2004 Freescale Semiconductor, Inc.
* 
* 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, sublicense,
* 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 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 NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS 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.
*
* Filename:     $Source$
* Author:       $Author$
* Locker:       $Locker$
* State:        $State$
* Revision:     $Revision$
*
******************************************************************************/

/*!
 * \file        bestcomm_api.h
 *
 * Bestcomm_api.h is the only header necessary for inclusion by user
 * code. The include path the C compiler searches to find .h files
 * should contain bestcomm/capi and one of bestcomm/code_dma/image_*.
 * This second entry selects which set of BestComm tasks will be used.
 * Of course the appropriate files in image_* must also be compiled and
 * linked.
 */

#include "../bestcomm/include/ppctypes.h"
#include "../bestcomm/include/mgt5200/sdma.h"
#include "../bestcomm/task_api/tasksetup_bdtable.h"
#include "../bestcomm/task_api/bestcomm_cntrl.h"
#include "../bestcomm/task_api/bestcomm_api_mem.h"

/*!
 * \brief       TaskSetup() debugging
 *
 * Define this macro as follows for debugging printf()s to see
 * what the API receives and sets from the TaskSetupParamSet_t
 * struct. Implemented in capi/task_api/tasksetup_general.h.
 *
 * \verbatim
 * >0  : print basic debug messages
 * >=10: also print C-API interface variables
 * >=20: also print task API interface variables
 * else: do nothing
 * \endverbatim
 */
#define DEBUG_BESTCOMM_API 0

/*!
 * \brief       Maximum number of tasks in the system.
 * This number is hardware-dependent and not user configuration.
 */
#define MAX_TASKS 16

/*
 * This may need to be removed in certain implementations.
 */
#ifndef NULL
# define NULL ((void *)0)
#endif  /* NULL */

typedef sint8 TaskId;
typedef sint32 BDIdx;

/*
 * Special "task IDs" for interrupt handling API functions
 */
/*! \brief      Debug interrupt "task ID" */
#define DEBUG_INTR_ID   SDMA_INT_BIT_DBG

/*! \brief      TEA interrupt "task ID" */
#define TEA_INTR_ID             SDMA_INT_BIT_TEA

/*! \brief      Task start autostart enable */
#define TASK_AUTOSTART_ENABLE   1

/*! \brief      Task start autostart disable */
#define TASK_AUTOSTART_DISABLE  0

/*! \brief      Task start interrupt enable */
#define TASK_INTERRUPT_ENABLE   1

/*! \brief      Task start interrupt disable */
#define TASK_INTERRUPT_DISABLE  0

/*
 * Buffer descriptor flags to pass to TaskBDAssign().
 */
/*! \brief      Transmit frame done */
#define TASK_BD_TFD     (1 << SDMA_DRD_BIT_TFD)

/*! \brief      Interrupt on frame done */
#define TASK_BD_INT     (1 << SDMA_DRD_BIT_INT)

/*!
 * \brief       Data transfer size
 */
typedef enum {
        SZ_FLEX         = 3,    /*!< invalid for TaskSetupParamSet_t */
        SZ_UINT8        = 1,    /*!< 1-byte     */
        SZ_UINT16       = 2,    /*!< 2-byte     */
        SZ_UINT32       = 4             /*!< 4-byte     */
} Sz_t;

/*!
 * \brief       API error codes
 */
typedef enum {
        TASK_ERR_NO_ERR                 = -1,   /*!< No error                                   */
        TASK_ERR_NO_INTR                = TASK_ERR_NO_ERR,
                                                                        /*!< No interrupt                               */
        TASK_ERR_INVALID_ARG    = -2,   /*!< Invalid function argument  */
        TASK_ERR_BD_RING_FULL   = -3,   /*!< Buffer descriptor ring full*/
        TASK_ERR_API_ALREADY_INITIALIZED
                                                        = -4,   /*!< API has already been initialized */
        TASK_ERR_SIZE_TOO_LARGE = -5,   /*!< Buffer descriptor cannot support size parameter */
        TASK_ERR_BD_RING_EMPTY  = -6,   /*!< Buffer descriptor ring is empty*/
        TASK_ERR_BD_BUSY                = -7,   /*!< The buffer descriptor is in use
                                                                                 by the BestComm                        */
        TASK_ERR_TASK_RUNNING   = -8    /*!< The task is running.               */

} TaskErr_t;

/*!
 * \brief       BestComm initiators
 *
 * These are assigned by TaskSetup().
 */
typedef enum {

        INITIATOR_ALWAYS        =  0,
        INITIATOR_SCTMR_0       =  1,
        INITIATOR_SCTMR_1       =  2,
        INITIATOR_FEC_RX        =  3,
        INITIATOR_FEC_TX        =  4,
        INITIATOR_ATA_RX        =  5,
        INITIATOR_ATA_TX        =  6,
        INITIATOR_SCPCI_RX      =  7,
        INITIATOR_SCPCI_TX      =  8,
        INITIATOR_PSC3_RX       =  9,
        INITIATOR_PSC3_TX       = 10,
        INITIATOR_PSC2_RX       = 11,
        INITIATOR_PSC2_TX       = 12,
        INITIATOR_PSC1_RX       = 13,
        INITIATOR_PSC1_TX       = 14,
        INITIATOR_SCTMR_2       = 15,

        INITIATOR_SCLPC         = 16,
        INITIATOR_PSC5_RX       = 17,
        INITIATOR_PSC5_TX       = 18,
        INITIATOR_PSC4_RX       = 19,
        INITIATOR_PSC4_TX       = 20,
        INITIATOR_I2C2_RX       = 21,
        INITIATOR_I2C2_TX       = 22,
        INITIATOR_I2C1_RX       = 23,
        INITIATOR_I2C1_TX       = 24,
        INITIATOR_PSC6_RX       = 25,
        INITIATOR_PSC6_TX       = 26,
        INITIATOR_IRDA_RX       = 25,
        INITIATOR_IRDA_TX       = 26,
        INITIATOR_SCTMR_3       = 27,
        INITIATOR_SCTMR_4       = 28,
        INITIATOR_SCTMR_5       = 29,
        INITIATOR_SCTMR_6       = 30,
        INITIATOR_SCTMR_7       = 31

} MPC5200Initiator_t;

/*!
 * \brief       Parameters for TaskSetup()
 *
 * All parameters can be hard-coded by the task API. Hard-coded values
 * will be changed in the struct passed to TaskSetup() for the user to
 * examine later.
 */
typedef struct {
        uint32  NumBD;                  /*!< Number of buffer descriptors                               */

        union {
           uint32 MaxBuf;               /*!< Maximum buffer size                                                */
           uint32 NumBytes;             /*!< Number of bytes to transfer                                */
        } Size;                                 /*!< Buffer size union for BD and non-BD tasks  */

        MPC5200Initiator_t
                        Initiator;              /*!< BestComm initiator (ignored if hard-wired) */
        uint32  StartAddrSrc;   /*!< Address of the DMA source (e.g. a FIFO)    */
        sint16  IncrSrc;                /*!< Amount to increment source pointer                 */
        Sz_t    SzSrc;                  /*!< Size of source data access                                 */
        uint32  StartAddrDst;   /*!< Address of the DMA destination (e.g. a FIFO) */
        sint16  IncrDst;                /*!< Amount to increment data pointer                   */
        Sz_t    SzDst;                  /*!< Size of destination data access                    */
} TaskSetupParamSet_t;

/*!
 * \brief       Parameters for TaskDebug()
 *
 * TaskDebug() and the contents of this data structure are yet to be
 * determined.
 */
typedef struct {
        int dummy;                              /* Some compilers don't like empty struct typedefs */
} TaskDebugParamSet_t;

/*!
 * \brief       Generic buffer descriptor.
 *
 * It is generally used as a pointer which should be cast to one of the
 * other BD types based on the number of buffers per descriptor.
 */
typedef struct {
        uint32 Status;                  /*!< Status and length bits             */
} TaskBD_t;

/*!
 * \brief       Single buffer descriptor.
 */
typedef struct {
        uint32 Status;                  /*!< Status and length bits             */
        uint32 DataPtr[1];              /*!< Pointer to data buffer             */
} TaskBD1_t;

/*!
 * \brief       Dual buffer descriptor.
 */
typedef struct {
        uint32 Status;                  /*!< Status and length bits             */
        uint32 DataPtr[2];              /*!< Pointer to data buffers    */
} TaskBD2_t;



/***************************
 * Start of API Prototypes
 ***************************/

#include "../bestcomm/bestcomm_priv.h"
#include "../bestcomm/dma_image.capi.h"
  
/*!
 * \brief       Initialize a single task.
 * \param       TaskName        Type of task to initialize. E.g. PCI transmit,
 *                                              ethernet receive, general purpose dual-pointer.
 *                                              Values expected can be found in the TaskName_t
 *                                              enum defined in dma_image.capi.h.
 * \param       TaskSetupParams Task-specific parameters. The user must fill out
 *                                              the pertinent parts of a TaskSetupParamSet_t
 *                                              data structure.
 * \returns TaskId task identification token which is a required
 *                      parameter for most other API functions.
 *
 * This function returns a task identification token which is a required
 * parameter for most other API functions.
 *
 * Certain values of the structure pointed to by TaskParams are set
 * as a side-effect based on task type. These may be examined after
 * a successful call to TaskSetup(). User-specified values may be
 * overridden.
 *
 * TaskId TaskSetup( TaskName_t TaskName,
 *                   TaskSetupParamSet_t *TaskSetupParams );
 */
#define                 TaskSetup(TaskName, TaskSetupParams)    \
                                TaskSetup_ ## TaskName (TaskName ## _api, TaskSetupParams)

const char              *TaskVersion(void);

int                             TasksInitAPI(uint8 *MBarRef);

int                             TasksInitAPI_VM(uint8 *MBarRef, uint8 *MBarPhys);

void                    TasksLoadImage(sdma_regs *sdma);
int                             TasksAttachImage(sdma_regs *sdma);

uint32                  TasksGetSramOffset(void);
void                    TasksSetSramOffset(uint32 sram_offset);

int                             TaskStart(TaskId taskId, uint32 autoStartEnable,
                                                  TaskId autoStartTask, uint32 intrEnable);
int                             TaskStop(TaskId taskId);
static int              TaskStatus(TaskId taskId);
BDIdx                   TaskBDAssign(TaskId taskId, void *buffer0, void *buffer1,
                                                         int size, uint32 bdFlags);
BDIdx                   TaskBDRelease(TaskId taskId);
BDIdx                   TaskBDReset(TaskId taskId);
static TaskBD_t *TaskGetBD(TaskId taskId, BDIdx bd);
static TaskBD_t *TaskGetBDRing(TaskId taskId);
int                             TaskDebug(TaskId taskId, TaskDebugParamSet_t *paramSet);
static int              TaskIntClear(TaskId taskId);
static TaskId   TaskIntStatus(TaskId taskId);
static int              TaskIntPending(TaskId taskId);
static TaskId   TaskIntSource(void);
static uint16   TaskBDInUse(TaskId taskId);


/*!
 * \brief       Get the enable/disable status of a task.
 * \param       taskId  Task handle passed back from a successful TaskSetup()
 * \returns     Boolean true indicates enabled or false indicates disabled
 *                      or invalid taskId.
 */
static inline int TaskStatus(TaskId taskId)
{
        return SDMA_TASK_STATUS(SDMA_TCR, taskId) & 0x8000;
}

/*!
 * \brief       Return a pointer to a buffer descriptor at index BDIdx
 * \param       taskId  Task handle passed back from a successful TaskSetup()
 * \param       bd              Buffer descriptor handle returned by
 *                                      TaskBDAssign() or TaskBDRelease().
 * \returns     Pointer to the requested buffer descriptor or NULL on error.
 *
 * The returned pointer should be cast to the appropriate buffer
 * descriptor type, TaskBD1_t or TaskBD2_t.
 */
static inline TaskBD_t *TaskGetBD(TaskId taskId, BDIdx bd)
{
        TaskBD_t *bdTab;

        bdTab = TaskBDIdxTable[taskId].BDTablePtr;
        if (TaskBDIdxTable[taskId].numPtr == 1) {
                return (TaskBD_t *)&(((TaskBD1_t *)bdTab)[bd]);
        } else {
                return (TaskBD_t *)&(((TaskBD2_t *)bdTab)[bd]);
        }
}

/*!
 * \brief       Return a pointer to the first buffer descriptor in the ring.
 * \param       taskId  Task handle passed back from a successful TaskSetup()
 * \returns     Pointer to the array of buffer descriptors making up the
 *                      ring or NULL on error.
 *
 * A device driver author may choose to use this in lieu of
 * TaskBDAssign()/TaskBDRelease() to get direct access to the
 * BD ring with the warning that the underlying data structure may change.
 * Use at one's own discretion.
 */
static inline TaskBD_t *TaskGetBDRing(TaskId taskId)
{
        return TaskBDIdxTable[taskId].BDTablePtr;
}

/*!
 * \brief       Clear the interrupt for a given BestComm task.
 * \param       taskId  Task handle passed back from a successful TaskSetup()
 * \returns     TASK_ERR_NO_ERR (which is not really an error) for success
 */
static inline int TaskIntClear(TaskId taskId)
{
        SDMA_CLEAR_IEVENT(SDMA_INT_PEND, taskId);
        return TASK_ERR_NO_ERR; /* success */
}

/*!
 * \brief       Get the interrupt status for a given task.
 * \param       taskId  Task handle passed back from a successful TaskSetup()
 * \returns     TASK_ERR_NO_INTR (which is not really an error) for no interrupt
 *                      pending, taskId for a regular interrupt, DEBUG_INTR_ID for
 *                      a debug interrupt and TEA_INTR_ID for a TEA interrupt.
 *                      \b Note: TaskIntStatus() may return 0, but this means that that
 *                      taskId 0 is interrupt pending.
 */
static inline TaskId TaskIntStatus(TaskId taskId)
{
        uint32 pending;

        pending = SDMA_INT_PENDING(SDMA_INT_PEND, SDMA_INT_MASK);

        if (SDMA_INT_TEST(pending, taskId)) {
                return taskId;
        } else if (SDMA_INT_TEST(pending, DEBUG_INTR_ID)) {
                return DEBUG_INTR_ID;
        } else if (SDMA_INT_TEST(pending, TEA_INTR_ID)) {
                return TEA_INTR_ID;
        }

        return TASK_ERR_NO_INTR;
}

/*!
 * \brief       Get the interrupt pending status for a given task.
 * \param       taskId  Task handle passed back from a successful TaskSetup()
 * \returns     0 if task does not have a pending interrupt. 1 if the task
 *                      has an interrupt pending.
 */
static inline int TaskIntPending(TaskId taskId)
{
        uint32 pending;

        pending = SDMA_INT_PENDING(SDMA_INT_PEND, SDMA_INT_MASK);
        if (SDMA_INT_TEST(pending, taskId)) {
                return 1;
        } else {
                return 0;
        }
}

/*!
 * \brief       Returns the task ID of an interrupting BestComm task.
 * \returns     TASK_ERR_NO_INTR (which is not really an error) for no interrupt
 *                      pending or the taskId of the interrupting task.
 *
 * The user must query TaskIntStatus() to discover if this is a debug
 * or TEA interrupt. This function is designed for use by an operating
 * system interrupt handler.
 */
static inline TaskId TaskIntSource(void)
{
        uint32 pending;
        uint32 mask = 1 << (MAX_TASKS - 1);
        TaskId i;

        pending = SDMA_INT_PENDING(SDMA_INT_PEND, SDMA_INT_MASK);

        if (SDMA_INT_TEST(pending, SDMA_INT_BIT_TEA)) {
                return (TaskId)SDMA_TEA_SOURCE(SDMA_INT_PEND);
        }

        for (i = (MAX_TASKS - 1); i >= 0; --i, mask >>= 1) {
                if (pending & mask) {
                        return i;
                }
        }

        return TASK_ERR_NO_INTR;
}

/*!
 * \brief       Get a count of in-use buffer descriptors.
 * \param       taskId  Task handle passed back from a successful TaskSetup()
 * \returns     Count of the current number of BDs in use by the given task.
 */
static inline uint16 TaskBDInUse(TaskId taskId)
{
        return TaskBDIdxTable[taskId].currBDInUse;
}

#endif  /* __BESTCOMM_API_H */