path: root/bsps/include/grlib/gr1553rt.h

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

/*  GR1553B RT driver
 *
 *  COPYRIGHT (c) 2010.
 *  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.
 */

#ifndef __GR1553RT_H__
#define __GR1553RT_H__

/* CONFIG OPTION: Maximum number of LIST IDs supported.
 *                There are two lists per RT subaddress, one for RX one
 *                for TX.
 */
#define RTLISTID_MAX 64

/* CONFIG OPTION: Maximum number of Interrupt handlers per device supported 
 * max is 256 supported, and minimum is 1.
 */
#define RTISR_MAX 64

/* CONFIG OPTION: Maximum number of transfer (RX/TX) descriptors supported.
 *
 * Set this option to zero to allow flexible number of descriptors,
 * requires dynamically allocation of driver structures.
 */
/*#define RTBD_MAX 4096*/
#define RTBD_MAX 0

#ifdef __cplusplus
extern "C" {
#endif

/* Register GR1553B driver needed by RT driver */
extern void gr1553rt_register(void);

struct gr1553rt_list;

/* Descriptor read/written by hardware.
 *
 * Must be aligned to 16 byte boundary 
 */
struct gr1553rt_bd {
	volatile unsigned int	ctrl;	/* 0x00 Control/Status word */
	volatile unsigned int	dptr;	/* 0x04 Data Pointer */
	volatile unsigned int	next;	/* 0x08 Next Descriptor in list */
	volatile unsigned int	unused;	/* 0x0C UNUSED BY HARDWARE */
};

/* Sub address table entry, the hardware access */
struct gr1553rt_sa {
	volatile unsigned int ctrl;	/* 0x00 SUBADDRESS CONTROL WORD */
	volatile unsigned int txptr;	/* 0x04 TRANSMIT BD POINTER */
	volatile unsigned int rxptr;	/* 0x08 RECEIVE BD POINTER */
	volatile unsigned int unused;	/* 0x0C UNUSED BY HARDWARE */
};

/* Configuration of a RT-SubAddress-List */
struct gr1553rt_list_cfg {
	unsigned int bd_cnt;		/* Number of hw-descriptors in list */
};

/* A TX or RX subaddress descriptor list */
struct gr1553rt_list {
	short listid;			/* ID/NUMBER of List. -1 unassigned */
	short subadr;			/* SubAddress. -1 when not scheduled */
	void *rt;			/* Scheduled on Device */
	struct gr1553rt_list_cfg *cfg;	/* List configuration */
	int bd_cnt;			/* Number of Descriptors */

	/* !!Must be last in data structure!! 
	 * !!Array must at least be of length bd_cnt!!
	 */
	unsigned short bds[0];		/* Array of BDIDs */
};

/* GR1553B-RT Driver configuration options used when calling gr1553rt_config().
 *
 * Note that if not custom addresses are given the driver will dynamically
 *      allocate memory for buffers.
 * Note that if custom addresses with the LSB set, the address will be
 *      interpreted as a address accessible by hardware, and translated
 *      into an address used by CPU.
 */
struct gr1553rt_cfg {
	unsigned char rtaddress;	/* RT Address 0..30 */

	/*** MODE CODE CONFIG ***/
	unsigned int modecode;		/* Mode codes enable/disable/IRQ/EV-Log.
					 * Each modecode has a 2-bit cfg field.
					 * See Mode Code Control Register in
					 * hardware manual.
					 */

	/*** TIME CONFIG ***/
	unsigned short time_res;	/* Time tag resolution in us */

	/*** SUBADDRESS TABLE CONFIG ***/
	void *satab_buffer;		/* Optional Custom buffer. Must be 
					 * At least 16*32 bytes, and be aligned
					 * to 10-bit (1KB) boundary. Set to NULL
					 * to make driver allocate buffer.
					 */

	/*** EVENT LOG CONFIG ***/
	void *evlog_buffer;		/* Optional Custom buffer */
	int evlog_size;			/* Length, must be a multiple of 2.
					 * If set to ZERO event log is disabled
					 */

	/*** TRANSFER DESCRIPTOR CONFIG ***/
	int bd_count;			/* Number of transfer descriptors shared
					 * by all RX/TX sub-addresses */
	void *bd_buffer;		/* Optional Custom descriptor area.
					 * Must hold bd_count*32 bytes.
					 * If NULL, descriptors will be 	
					 * allocated dynamically. */
};

/* GR1553B-RT status indication, copied from the RT registers and stored
 * here. Used when calling the gr1553rt_status() function.
 */
struct gr1553rt_status {
	unsigned int status;		/* RT Status word */
	unsigned int bus_status;	/* BUS Status */
	unsigned short synctime;	/* Time Tag of last sync with data */
	unsigned short syncword;	/* Data of last mode code synchronize
					 * with data. */
	unsigned short time_res;	/* Time resolution (set by config) */
	unsigned short time;		/* Current Time Tag */
};

/* ISR callback definition for ERRORs detected in the GR1553B-RT interrupt
 * handler.
 *
 * \param err    Inidicate Error type. The IRQ flag register bit mask:
 *                 Bit 9  - RT DMA ERROR
 *                 Bit 10 - RT Table access error
 * \param data   Custom data assigned by user
 */
typedef void (*gr1553rt_irqerr_t)(int err, void *data);

/* ISR callback definition for modecodes that are configured to generate
 * an IRQ. The callback is called from within the GR1553B-RT interrupt
 * handler.
 *
 * \param mcode  Mode code that caused this IRQ
 * \param entry  The raw Eventlog Entry
 * \param data   Custom data assigned by user
 */
typedef void (*gr1553rt_irqmc_t)(int mcode, unsigned int entry, void *data);

/* Transfer ISR callback definition. Called from GR1553B-RT interrupt handler
 * when an interrupt has been generated and a event logged due to a 1553
 * transfer to this RT.
 *
 * \param list     List (Subaddress/TransferType) that caused IRQ
 * \param entry    The raw Eventlog Entry
 * \param bd_next  Next Descriptor-entry index in the list (Subaddress/tr-type)
 *                 This can be used to process all descriptors upto entry_next.
 * \param data     Custom data assigned by user
 */
typedef void (*gr1553rt_irq_t)(
	struct gr1553rt_list *list, 
	unsigned int entry,
	int bd_next,
	void *data
	);

/* Configure a list according to configuration. Assign the list
 * to a device, however not to a RT sub address yet. The rt
 * is stored within list.
 *
 * \param rt       RT Device driver identification, stored within list.
 * \param list     The list to configure
 * \param cfg      Configuration for list. Pointer to configuration is
 *                 stored within list for later use.
 */
extern int gr1553rt_list_init
	(
	void *rt,
	struct gr1553rt_list **plist,
	struct gr1553rt_list_cfg *cfg
	);

/* Assign an Error Interrupt handler. Before the handler is called the 
 * RT hardware is stopped/disabled. The handler is optional, if not assigned
 * the ISR will still stop the RT upon error.
 *
 * Errors detected by the interrupt handler:
 *  - DMA error
 *  - Subaddress table access error
 *
 * \param func     ISR called when an error causes an interrupt.
 * \param data     Custom data given as an argument when calling ISR
 */
extern int gr1553rt_irq_err
	(
	void *rt,
	gr1553rt_irqerr_t func,
	void *data
	);

/* Assign a ModeCode Interrupt handler callback. Called when a 1553 modecode
 * transfer is logged and cause an IRQ. The modecode IRQ generation is
 * configured from "struct gr1553rt_cfg" when calling gr1553rt_config().
 *
 * \param func     ISR called when a modecode causes an interrupt.
 * \param data     Custom data given as an argument when calling ISR
 */
extern int gr1553rt_irq_mc
	(
	void *rt,
	gr1553rt_irqmc_t func,
	void *data
	);

/* Assign transfer interrupt handler callback. Called when a RX or TX
 * transfer is logged and cause an interrupt, the function is called
 * from the GR1553B-RT driver's ISR, in interrupt context.
 *
 * The callback can be installed per subaddress and transfer type.
 * Subaddress 0 and 31 are not valid (gr1553rt_irq_mc() for modecodes).
 *
 * \param subadr   Select subaddress (1-30)
 * \param tx       1=TX subaddress, 0=RX subaddress
 * \param func     ISR called when subaddress of spcified transfer type
 *                 causes an interrupt.
 * \param data     Custom data given as an argument when calling ISR
 */
extern int gr1553rt_irq_sa
	(
	void *rt,
	int subadr,
	int tx,
	gr1553rt_irq_t func,
	void *data
	);

#define GR1553RT_BD_FLAGS_IRQEN (1<<30)
/* Initialize a descriptor entry in a list. This is typically done
 * prior to scheduling the list.
 *
 * \param entry_no  Entry number in list (descriptor index in list)
 * \param flags     Enable IRQ when descriptor is accessed by setting 
 *                  argument GR1553RT_BD_FLAGS_IRQEN. Enabling IRQ on a
 *                  descriptor basis will override SA-table IRQ config.
 * \param dptr      Data Pointer to RX or TX operation. The LSB indicate
 *                  if the address must be translated into Hardware address
 *                  - this is useful when a buffer close to CPU is used
 *                  as a data pointer and the RT core is located over PCI.
 * \param next      Next Entry in list. Set to 0xffff for end of list. Set
 *                  0xfffe for next entry in list, wrap around to entry
 *                  zero if entry_no is last descriptor in list (circular).
 */
extern int gr1553rt_bd_init(
	struct gr1553rt_list *list,
	unsigned short entry_no,
	unsigned int flags,
	uint16_t *dptr,
	unsigned short next
	);

/* Manipulate/Read Control/Status and Data Pointer words of a buffer descriptor.
 * If status is zero, the control/status word is accessed. If dptr is non-zero
 * the data pointer word is accessed.
 *
 * \param list       The list that the descriptor is located at
 *
 * \param entry_no   The descriptor number accessed
 *
 * \param status     IN/OUT. If zero no effect. If pointer is non-zero the
 *                   value pointed to:
 *                   IN: Written to Control/Status
 *                   OUT: the value of the Control/Status word before writing.
 *
 * \param dptr       IN/OUT. If zero no effect. If pointer is non-zero, the
 *                   value pointed to:
 *                   IN: non-zero: Descriptor data pointer will be updated with
 *                       this value. Note that the LSB indicate if the address
 *                       must be translated into hardware-aware address.
 *                   OUT: The old data pointer is stored here.
 */
extern int gr1553rt_bd_update(
	struct gr1553rt_list *list,
	int entry_no,
	unsigned int *status,
	uint16_t **dptr
	);

/* Get the next/current descriptor processed of a RT sub-address.
 *
 * \param subadr  RT Subaddress
 * \param txeno   Pointer to where TX descriptor number is stored.
 * \param rxeno   Pointer to where RX descriptor number is stored.
 */
extern int gr1553rt_indication(void *rt, int subadr, int *txeno, int *rxeno);

/* Take a GR1553RT hardware device identified by minor.
 * A pointer is returned that is used internally by the GR1553RT
 * driver, it is used as an input parameter 'rt' to all other
 * functions that manipulate the hardware.
 *
 * This function initializes the RT hardware to a stopped/disable level.
 */
extern void *gr1553rt_open(int minor);

/* Close and stop/disable the RT hardware. */
extern void gr1553rt_close(void *rt);

/* Configure the RT. The RT device must be configured once before
 * started. A started RT device can not be configured.
 *
 * \param rt    The RT to configure
 * \param cfg   Configuration parameters
 */
extern int gr1553rt_config(void *rt, struct gr1553rt_cfg *cfg);

/* Schedule a RX or TX list on a sub address. If a list has already been
 * schduled on the subaddress and on the same transfer type (RX/TX), the 
 * old list is replaced with the list given here.
 *
 * \param subadr   Subaddress to schedule list on
 * \param tx       Subaddress transfer type: 1=TX, 0=RX
 * \param list     Preconfigued RT list scheduled
 */
extern void gr1553rt_sa_schedule(
	void *rt,
	int subadr,
	int tx,
	struct gr1553rt_list *list
	);

/* Set SubAdress options. One may for example Enable or Disable a sub 
 * address RX and/or TX. See hardware manual for SA-Table configuration
 * options.
 *
 * \param subadr   SubAddress to configure
 * \param mask     Bit mask of option-bits written to subaddress config
 * \param options  The new options written to subaddress config.
 *
 */
extern void gr1553rt_sa_setopts(
	void *rt,
	int subadr,
	unsigned int mask,
	unsigned int options
	);

/* Get The Subaddress and transfer type of a scheduled list. Normally the
 * application knows which subaddress the list is for.
 *
 * \param list     List to lookup information for
 * \param subadr   Pointer to where the subaddress is stored
 * \param tx       Transfer type is stored here. 1=TX, 0=RX.
 */
extern void gr1553rt_list_sa(
	struct gr1553rt_list *list,
	int *subadr,
	int *tx
	);

/* Start RT Communication
 *
 * Interrupts will be enabled. The RT enabled and the "RT-run-time" 
 * part of the API will be opened for the user and parts that need the
 * RT to be stopped are no longer available. After the RT has been
 * started the configuration function can not be called.
 */
extern int gr1553rt_start(void *rt);

/* Get Status of the RT core. See data structure gr1553rt_status for more
 * information about the result. It can be used to read out:
 *  - time information
 *  - sync information
 *  - bus & RT status
 *
 * \param status   Pointer to where the status words will be stored. They
 *                 are stored according to the gr1553rt_status data structure.
 */
extern void gr1553rt_status(void *rt, struct gr1553rt_status *status);

/* Stop RT communication. Only possible to stop an already started RT device.
 * Interrupts are disabled and the RT Enable bit cleared.
 */
extern void gr1553rt_stop(void *rt);

/* Set RT vector and/or bit word.
 *
 *  - Vector Word is used in response to "Transmit vector word" BC commands
 *  - Bit Word is used in response to "Transmit bit word" BC commands
 *
 *
 * \param mask     Bit-Mask, bits that are 1 will result in that bit in the
 *                 words register being overwritten with the value of words
 * \param words    Bits 31..16: Bit Word. Bits 15..0: Vector Word.
 *
 * Operation:
 *  hw_words = (hw_words & ~mask) | (words & mask)
 */
extern void gr1553rt_set_vecword(
	void *rt,
	unsigned int mask,
	unsigned int words
	);

/* Set selectable bits of the "Bus Status Register". The bits written
 * is determined by the "mask" bit-mask. Operation:
 *
 * bus_status = (bus_status & ~mask) | (sts & mask)
 * 
 */
extern void gr1553rt_set_bussts(void *rt, unsigned int mask, unsigned int sts);

/* Read up to MAX number of entries in eventlog log. 
 *
 * \param dst   Destination address for event log entries
 * \param max   Maximal number of event log entries that an be stored into dst
 *
 * Return
 *  negative   Failure
 *  zero       No entries available at the moment
 *  positive   Number of entries copied into dst
 */
extern int gr1553rt_evlog_read(void *rt, unsigned int *dst, int max);

#ifdef __cplusplus
}
#endif

#endif