/* 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
