source: rtems/bsps/shared/grlib/slink/grslink.c

/* SPDX-License-Identifier: BSD-2-Clause */

/*
 * This file contains the RTEMS GRSLINK SLINK master driver
 *
 * COPYRIGHT (c) 2009.
 * Cobham Gaisler AB.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * Comments concerning current driver implementation:
 *
 * The SLINK specification says that there are three IO cards that are capable 
 * of transmitting data. But these IO cards can have the address range 0 to 3, 
 * and an 'For information only' comment explains that the current 
 * implementation has receive buffers for ".. x 4 (IO cards)".
 * Because of this the driver has four queues, one for each IO card 0 - 3. 
 * When the addressing convention used for the IO cards is known, the number of
 * queues may be lowered to three.
 *
 */

#include <stdlib.h>

#include <bsp.h>
#include <grlib/grslink.h>
#include <grlib/ambapp.h>
#include <grlib/grlib.h>

#include <grlib/grlib_impl.h>

#ifndef GAISLER_SLINK
#define GAISLER_SLINK 0x02F
#endif

/* Enable debug output? */
/* #define DEBUG */

#ifdef DEBUG
#define DBG(x...) printk(x)
#else
#define DBG(x...) 
#endif

/* Bits and fields in SLINK transmit word */
#define SLINK_RW (1 << 23)
#define SLINK_CHAN_POS 16

/* Local types */
typedef struct {
        volatile unsigned int clockscale;
        volatile unsigned int ctrl;
        volatile unsigned int nullwrd;
        volatile unsigned int sts;
        volatile unsigned int msk;
        volatile unsigned int abase;
        volatile unsigned int bbase;
        volatile unsigned int td;
        volatile unsigned int rd;
} SLINK_regs;

typedef struct {
        char readstat;         /* Status of READ operation */
        char seqstat;          /* Status of SEQUENCE operation */
        unsigned char scnt;    /* Number of SEQUENCE words transferred */
} SLINK_status;

typedef struct {
        int size;
        unsigned int *buf;
        unsigned int *first;
        unsigned int *last;
        unsigned int *max;
        int full;
} SLINK_queue;

typedef struct {
        SLINK_regs    *reg;     /* Pointer to core registers */
        SLINK_status  *status;  /* Driver status information */
        void          (*slink_irq_handler)(int); /* Handler for INTERRUPT */
        void          (*slink_seq_change)(int); /* Callback on SEQUENCE change */
        int           rword;    /* Placeholder for READ response */
        rtems_id      read_sem; /* Semaphore for blocking SLINK_read */
        SLINK_queue   *queues;  /* Receive queues */
#ifdef SLINK_COLLECT_STATISTICS
        SLINK_stats   *stats;   /* Core statistics, optional */
#endif
} SLINK_cfg;


static SLINK_cfg *cfg = NULL;

/**** SLINK driver queues for unsolicited and INTERRUPT requests ****/

/* Function: SLINK_createqueues
 * Arguments: size: Number of elements in each queue
 * Returns: 0 on success, -1 on failure
 * Description: Creates SLINK_NUMQUEUES queues, one for each IO card 
 * that can send data. The pointers to the queues is saved in the driver 
 * config structure.
 */
static int SLINK_createqueues(int size)
{
        SLINK_queue *q;
        int i, j;

        if ((q = grlib_malloc(SLINK_NUMQUEUES*sizeof(*q))) == NULL)
                goto slink_qiniterr1;
                
        for (i = 0; i < SLINK_NUMQUEUES; i++) {
                q[i].size = size;
                if ((q[i].buf = grlib_malloc(size*sizeof(int))) == NULL)
                        goto slink_qiniterr2;
                q[i].first = q[i].last = q[i].buf;
                q[i].max = q[i].buf + (size-1);
                q[i].full = 0;
        }

        cfg->queues = q;

        return 0;
        
 slink_qiniterr2:
        for (j = 0; j < i; j++)
                free(q[i].buf);
        free(q);
 slink_qiniterr1:
        return -1;
}

/*
 * Function: SLINK_destroyqueues
 * Arguments: None
 * Returns: Nothing
 * Description: Frees the memory occupied by the queues in cfg->queues
 */
/*
  static void SLINK_destroyqueues(void)
  {
        int i;
        
        for(i = 0; i < SLINK_NUMQUEUES; i++)
                free(cfg->queues[i].buf);

        free(cfg->queues);
}
*/

/*
 * Function: SLINK_enqueue
 * Arguments: Received SLINK word
 * Returns: Nothing
 * Description: 
 */
static void SLINK_enqueue(unsigned int slink_wrd)
{
        SLINK_queue *ioq = cfg->queues + SLINK_WRD_CARDNUM(slink_wrd); 

        if (!ioq->full && SLINK_WRD_CARDNUM(slink_wrd) < SLINK_NUMQUEUES) {
                *ioq->last = slink_wrd;
                ioq->last = (ioq->last >= ioq->max) ? ioq->buf : ioq->last+1;
                ioq->full = ioq->last == ioq->first;
                return;
        }
#ifdef SLINK_COLLECT_STATISTICS
        cfg->stats->lostwords++;
#endif
}

/**** SLINK driver helper functions ****/

/*
 * Function: SLINK_getaddr
 * Arguments: amba_conf 
 *            base: assigned to base of core registers
 *            irq: assigned to core irq lines
 * Returns: Base address and IRQ via arguments, 0 if core is found, else -1
 * Description: See above.
 */
static int SLINK_getaddr(int *base, int *irq)
{       
        struct ambapp_apb_info c;

        if (ambapp_find_apbslv(ambapp_plb(),VENDOR_GAISLER,GAISLER_SLINK,&c) == 1) {
                *base = c.start;
                *irq = c.common.irq;
                return 0;
        }
        return -1;
}

/* Function: SLINK_calcscaler
 * Arguments: sysfreq: System frequency in Hz
 * Returns: Clock scaler register value
 * Description: Calculates value for SLINK clock scaler register to attain
 * a SLINK bus frequency as close to 6 MHz as possible. Please see the IP core 
 * documentation for a description of how clock scaling is implemented. 
 */
static int SLINK_calcscaler(int sysfreq)
{
        int fact = sysfreq / SLINK_FREQ_HZ;
        return ((fact/2-1) << 16) | (fact % 2 ? fact/2 : fact/2-1);  
}


/*
 * Function: SLINK_getsysfreq
 * Arguments: None
 * Returns: System frequency in Hz, or 0 if system timer is not found.
 * Description: Looks at the timer to determine system frequency. Makes use
 * of AMBA Plug'n'Play. 
 */
static int SLINK_getsysfreq(void)
{
        struct ambapp_apb_info t;
        struct gptimer_regs *tregs;
                
        if (ambapp_find_apbslv(ambapp_plb(),VENDOR_GAISLER,GAISLER_GPTIMER,&t)==1) {
                tregs = (struct gptimer_regs *)t.start;
                DBG("SLINK_getsysfreq returning %d\n", 
                    (tregs->scaler_reload+1)*1000*1000);
                return (tregs->scaler_reload+1)*1000*1000;
        }
        return 0;
}

/*
 * Function: SLINK_interrupt_handler
 * Arguments: v: not used
 * Returns: Nothing
 * Description: Interrupt handles checks RNE, SEQUENCE and error status
 * bits. Reads word from receive queue and distinguishes between INTERRUPT,
 * READ responses and SLAVE-WORD-SEND. When an INTERRUPT transfer is detected
 * the handler calls the user specified slink_irq_handler with the received
 * word. READ responses are saved and given to SLINK_read via a private
 * variable. SLAVE-WORD-SEND transfers are placed in the IO card's receive
 * queue.
 */
static rtems_isr SLINK_interrupt_handler(void *v)
{
        unsigned int sts;
        unsigned int wrd;

        /* Read all words from Receive queue */
        while ((sts = cfg->reg->sts) & SLINK_S_RNE) {

                /* Read first word in receive queue */
                wrd = cfg->reg->rd;
        
                /* Check channel value to determine action */
                switch (SLINK_WRD_CHAN(wrd)) {
                case 0: /* Interrupt */
                        cfg->slink_irq_handler(wrd);
#ifdef SLINK_COLLECT_STATISTICS
                        cfg->stats->interrupts++;
#endif
                        break;
                case 3: /* Read response, if no active READ, fall-through */
                        if (cfg->status->readstat == SLINK_ACTIVE) {
                                rtems_semaphore_release(cfg->read_sem);
                                cfg->status->readstat = SLINK_COMPLETED;
                                cfg->rword = wrd;
                                break;
                        }
                default: /* Unsolicited request */
                        SLINK_enqueue(wrd);
                        break;
                }
        }

        /* Check sequence operation */
        if (sts & SLINK_S_SC) {
                /* SEQUENCE completed */
                cfg->status->seqstat = SLINK_COMPLETED;
                if (cfg->slink_seq_change)
                        cfg->slink_seq_change(SLINK_COMPLETED);
#ifdef SLINK_COLLECT_STATISTICS
                cfg->stats->seqcomp++;
#endif
        } else if (sts & SLINK_S_SA) {
                /* SEQUENCE aborted */
                cfg->status->seqstat = SLINK_ABORTED;
                cfg->status->scnt = (sts >> SLINK_S_SI_POS);
                if (cfg->slink_seq_change)
                        cfg->slink_seq_change(SLINK_ABORTED);
        }

        /* Check error conditions */
        if (sts & SLINK_S_PERR) {
                /* 
                   Parity error detected, set seqstat if there is an ongoing 
                   sequence so that the calling application can decide if the
                   sequence should be aborted 
                */
                if (cfg->status->seqstat == SLINK_ACTIVE) {
                        cfg->status->seqstat = SLINK_PARERR;
                        if (cfg->slink_seq_change)
                                cfg->slink_seq_change(SLINK_PARERR);
                }
                /* Abort READ operation */
                if (cfg->status->readstat == SLINK_ACTIVE) {
                        cfg->status->readstat = SLINK_PARERR;
                        rtems_semaphore_release(cfg->read_sem);
                }
#ifdef SLINK_COLLECT_STATISTICS
                cfg->stats->parerr++;
#endif
        } 
        if (sts & SLINK_S_AERR) {
                /* AMBA error response, sequence aborted */
                cfg->status->seqstat = SLINK_AMBAERR;
                cfg->status->scnt = sts >> SLINK_S_SI_POS;
                if (cfg->slink_seq_change)
                        cfg->slink_seq_change(SLINK_AMBAERR);
        }
        if (sts & SLINK_S_ROV) {
                /* Receive overflow, abort any ongoing READ */ 
                if (cfg->status->readstat == SLINK_ACTIVE) {
                        cfg->status->readstat = SLINK_ROV;
                        rtems_semaphore_release(cfg->read_sem);
                }
#ifdef SLINK_COLLECT_STATISICS
                cfg->status->recov++;
#endif
        }

        /* Clear processed bits */
        cfg->reg->sts = sts;
}

/**** SLINK driver interface starts here ****/

/* Function: SLINK_init
 * Arguments: nullwrd: NULL word
 *            parity: Even (0) or Odd (1) parity
 *            interrupt_trans_handler: Function that handles interrupt requests
 *            sequence_callback: Callback on SEQUENCE status changes
 *            qsize: Size of each receive queue
 * Returns: 0 on success, -1 on failure
 * Description: Initializes the SLINK core
 */
int SLINK_init(unsigned int nullwrd, int parity, int qsize,
               void (*interrupt_trans_handler)(int),
               void (*sequence_callback)(int))
{
        int base;
        int irq;
        rtems_status_code st;

        /* Allocate private config structure */
        if (cfg == NULL && (cfg = grlib_malloc(sizeof(*cfg))) == NULL) {
                DBG("SLINK_init: Could not allocate cfg structure\n");
                goto slink_initerr1;
        }
        
        /* Create simple binary semaphore for blocking SLINK_read */
        st = rtems_semaphore_create(rtems_build_name('S', 'L', 'R', '0'), 0, 
                                    (RTEMS_FIFO|RTEMS_SIMPLE_BINARY_SEMAPHORE|
                                     RTEMS_NO_INHERIT_PRIORITY|RTEMS_LOCAL|
                                     RTEMS_NO_PRIORITY_CEILING), 0,
                                    &cfg->read_sem);
        if (st != RTEMS_SUCCESSFUL) {
                DBG("SLINK_init: Could not create semaphore\n");
                goto slink_initerr1;
        }
  
        /* Initialize pointer to SLINK core registers and get IRQ line */
        if (SLINK_getaddr(&base, &irq) == -1) {
                DBG("SLINK_init: Could not find core\n");
                goto slink_initerr2;
        }
        cfg->reg = (SLINK_regs*)base;

        /* Allocate status structure and initialize members */
        if ((cfg->status = grlib_calloc(1, sizeof(*cfg->status))) == NULL) {
                DBG("SLINK_init: Could not allocate status structure\n");
                goto slink_initerr2;
        }
        cfg->status->seqstat = SLINK_COMPLETED;
        cfg->status->readstat = SLINK_COMPLETED;

#ifdef SLINK_COLLECT_STATISTICS
        /* Allocate statistics structure and initialize members */
        if ((cfg->stats = grlib_calloc(1, sizeof(*cfg->stats))) == NULL) {
                DBG("SLINK_init: Could not allocate statistics structure\n");
                goto slink_initerr3;
        }
#endif

        /* Allocate and initialize queues */
        if (SLINK_createqueues(qsize) == -1) {
                DBG("SLINK_init: Could not create queues\n");
                goto slink_initerr3;
        }

        /* Configure core registers */
        cfg->reg->clockscale = SLINK_calcscaler(SLINK_getsysfreq());
        cfg->reg->ctrl = parity ? SLINK_C_PAR : 0;
        cfg->reg->nullwrd = nullwrd;
        cfg->reg->msk = (SLINK_M_PERRE | SLINK_M_AERRE | SLINK_M_ROVE |
                         SLINK_M_RNEE | SLINK_M_SAE | SLINK_M_SCE);

        /* Set-up INTERRUPT transfer handling */
        cfg->slink_irq_handler = interrupt_trans_handler;

        /* Save SEQUENCE callback */
        cfg->slink_seq_change = sequence_callback;

        /* Set-up IRQ handling */
        rtems_interrupt_handler_install(irq, "slink",
                        RTEMS_INTERRUPT_SHARED,
                        SLINK_interrupt_handler, NULL);
        
        return 0;

 slink_initerr3:
        free(cfg->status);
 slink_initerr2:
        free(cfg);
 slink_initerr1:
        return -1;
}

/* Function: SLINK_start
 * Description: Enables the core
 */
void SLINK_start(void)
{   
        if (cfg != NULL)
                cfg->reg->ctrl |= SLINK_C_SLE;
}

/* Function: SLINK_stop
 * Description: Disables the core
 */
void SLINK_stop(void)
{
        if (cfg != NULL)
                cfg->reg->ctrl &= ~SLINK_C_SLE;
}

/*
 * Function: SLINK_read
 * Arguments: data: Payload of data word
 *            channel: -
 *            reply: Reply from IO card
 * Returns: 0 on success
 *          -(SLINK_PARERR, SLINK_ROV) on error or -SLINK_QFULL if transmit queue
 *          is full and software should try again.
 * Description: Reads one word and returns the response in *reply unless there
 *              is an error. This function blocks until the READ operation is
 *              completed or aborted.
 */
int SLINK_read(int data, int channel, int *reply)
{       
        DBG("SLINK_read: called..");

        if (cfg->reg->sts & SLINK_S_TNF) {
                cfg->status->readstat = SLINK_ACTIVE;
                cfg->reg->td = SLINK_RW | channel << SLINK_CHAN_POS | data;
        } else {
                DBG("queue FULL\n");
                return -SLINK_QFULL; /* Transmit queue full */
        }

        /* Block until the operation has completed or has been aborted */
        rtems_semaphore_obtain(cfg->read_sem, RTEMS_WAIT, RTEMS_NO_TIMEOUT);

        if (cfg->status->readstat == SLINK_COMPLETED) {
                *reply = cfg->rword; 
#ifdef SLINK_COLLECT_STATISTICS
                cfg->stats->reads++;
#endif       
                DBG("returning 0\n");
                return 0;
        } else {
                DBG("returning error code\n");
                return -cfg->status->readstat;
        }
}

/*
 * Function: SLINK_write
 * Arguments: data: Payload of SLINK data word
 *            channel: Channel value (bits 22 downto 16) of receive 
 *                     register word
 * Returns: 0 if command was placed in transmit queue
 *          -SLINK_QFULL if transmit queue was full (software should retry)
 * Description: See above.
 */
int SLINK_write(int data, int channel)
{ 
        if (cfg->reg->sts & SLINK_S_TNF) {
                cfg->reg->td = channel << SLINK_CHAN_POS | data;
#ifdef SLINK_COLLECT_STATISTICS
                cfg->stats->writes++;
#endif
                return 0;
        }

        return -SLINK_QFULL;    
}

/*
 * Function: SLINK_sequence
 * Arguments: a: Array containing sequence commands
 *            b: Array where SEQUENCE responses will be stored
 *            n: Number of commands in a array
 *            channel: Sequence Channel Number
 *            reconly: Set to 1 if the SEQUENCE operation is receive only
 * Returns: 0 if SEQUENCE could be started (SUCCESS)
 *          -1 if SEQUNCE was not started due to ongoing SEQUENCE
 */
int SLINK_seqstart(int *a, int *b, int n, int channel, int reconly)
{  
        /* Only start a new SEQUENCE of the former SEQUENCE has completed */
        if (cfg->status->seqstat == SLINK_ACTIVE || 
            cfg->status->seqstat == SLINK_PARERR)
                return -1;

        /* Tell core about arrays */
        cfg->reg->abase = (int)a;
        cfg->reg->bbase = (int)b;
        
        /* As far as software is concerned the sequence is now active */
        cfg->status->seqstat = SLINK_ACTIVE;

        /* Enable SEQUENCE operation with SCN = channel and SLEN = n-1 */
        if (reconly == 1) {
           cfg->reg->ctrl = (((n-1) << SLINK_C_SLEN_POS) | SLINK_C_SRO |
                             (channel << SLINK_C_SCN_POS) |
                             SLINK_C_SE | (cfg->reg->ctrl & 0xC000000F));
        } else {
           cfg->reg->ctrl = (((n-1) << SLINK_C_SLEN_POS) |
                             (channel << SLINK_C_SCN_POS) |
                             SLINK_C_SE | (cfg->reg->ctrl & 0xC000000F));
        }

#ifdef SLINK_COLLECT_STATISTICS
        cfg->stats->sequences++;
#endif

        return 0;
}


/* Function: SLINK_seqabort
 * Description: This function aborts an ongoing SEQUENCE. Software can tell
 * when the SEQUENCE is aborted by polling SLINK_seqstat().
 */
void SLINK_seqabort(void)
{
        cfg->reg->ctrl = cfg->reg->ctrl | SLINK_C_AS;
}


/*
 * Function: SLINK_seqstatus
 * Returns: The current or status of the SEQUENCE operation:
 *          SLINK_COMPLETED, SLINK_ACTIVE, SLINK_PARERR, SLINK_AMBAERR,
 *          SLINK_ABORTED (these are defined in bsp/grslink.h)
 * Description: Meaning of returned values:
 *              SLINK_ABORTED: Aborted before all operations completed.
 *              SLINK_ACTIVE: The core is busy processing the SEQUENCE
 *              SLINK_AMBAERR: The last SEQUENCE was aborted by an AMBA ERROR
 *              SLINK_COMPLETED: All words were transferred in the last SEQUENCE
 *              SLINK_PARERR: Parity error detected. Software may want to abort
 *
 *              If the SEQUENCE was aborted SLINK_seqwrds() can be used to
 *              determine the number of completed operations.
 */
int SLINK_seqstatus(void)
{
        return cfg->status->seqstat;
}

/*
 * Function: SLINK_seqwrds
 * Returns: -1 for ongoing sequence
 *          0 if all words were transferred in the last sequence
 *          number of words if the last SEQUENCE did not complete 
 *          (SLINK_AMBAERR or SLINK_ABORTED is reported ny SLINK_seqstatus()) 
 */
int SLINK_seqwrds(void)
{
        switch (cfg->status->seqstat) {
        case SLINK_COMPLETED: return 0;
        case SLINK_ACTIVE | SLINK_PARERR: return -1;
        default: return cfg->status->scnt;
        }
}

/* 
 * Function: SLINK_hwstatus
 * Returns: The SLINK core's status register. The register values can be 
 *          interpreted with the help of macros defined in bsp/grslink.h.
 */
int SLINK_hwstatus(void)
{
        return cfg->reg->sts;
}

/*
 * Function: SLINK_queuestatus
 * Arguments: iocard: Queue which to check status for
 * Returns: Number of elements in queue or -1 on non-existent queue
 * Description: SLINK_queuestatus(queue) returns the number of elements in
 *              queue 'iocard'
 */
int SLINK_queuestatus(int iocard)
{       
        unsigned int first, last;
        SLINK_queue *ioq;
        
        if (iocard >= SLINK_NUMQUEUES)
                return -1;

        ioq = cfg->queues + iocard;

        if (ioq->full)
                return ioq->size;
        if (ioq->first == ioq->last)
                return 0;

        first = ((unsigned int)ioq->first)/sizeof(unsigned int);
        last = ((unsigned int)ioq->last)/sizeof(unsigned int);
        
        return first < last ? last - first : ioq->size - first + last; 
}

/*
 * Function: SLINK_dequeue
 * Arguments: iocard: IO card number
 *            elem: First element in IO card queue
 * Returns: 0 on success or -1 on empty or non-existent queue
 * Description: 
 */
int SLINK_dequeue(int iocard, int *elem)
{       
        if (iocard >= SLINK_NUMQUEUES)
                return -1;
        
        SLINK_queue *ioq = cfg->queues + iocard;
        
        if (ioq->last != ioq->first || ioq->full) {
                *elem = *ioq->first;
                ioq->first = (ioq->first >= ioq->max) ? ioq->buf : ioq->first+1;
                ioq->full = 0;
                return 0;
        }
        return -1;
}

/*
 * Function: SLINK_statistics
 * Returns: If the core has statistics colletion enabled this function returns
 * a pointer to a struct containing statistics information, otherwise NULL.
 */
SLINK_stats *SLINK_statistics(void)
{
#ifdef SLINK_COLLECT_STATISTICS
        return cfg->stats;
#else
        return NULL;
#endif
}