include/grlib/gr1553bc.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /* GR1553B BC driver
0004  *
0005  * COPYRIGHT (c) 2010.
0006  * Cobham Gaisler AB.
0007  *
0008  * Redistribution and use in source and binary forms, with or without
0009  * modification, are permitted provided that the following conditions
0010  * are met:
0011  * 1. Redistributions of source code must retain the above copyright
0012  *    notice, this list of conditions and the following disclaimer.
0013  * 2. Redistributions in binary form must reproduce the above copyright
0014  *    notice, this list of conditions and the following disclaimer in the
0015  *    documentation and/or other materials provided with the distribution.
0016  *
0017  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0018  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0020  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0021  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0022  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0023  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0025  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0026  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0027  * POSSIBILITY OF SUCH DAMAGE.
0028  *
0029  * OVERVIEW
0030  * ========
0031  * This driver controls the BC device, located at an on-chip AMBA or an
0032  * AMBA-over-PCI bus. The driver operates the BC device and provides you
0033  * with interrupt services and core control. The driver start execution of
0034  * a synchronuos and/or an asynchronous BC descriptor List. The list contains
0035  * a descriptor table and a software description to make some operations
0036  * possible, for example translate descriptor-address into descriptor-number.
0037  *
0038  * BC descriptors are generated by the list API, available in gr1553bc_list.h.
0039  *
0040  * See gr1553bc_list.h for more information.
0041  */
0042
0043 #ifndef __GR1553BC_H__
0044 #define __GR1553BC_H__
0045
0046 #ifdef __cplusplus
0047 extern "C" {
0048 #endif
0049
0050 /* Forward declaration */
0051 struct gr1553bc_list;
0052 struct gr1553bc_major;
0053 struct gr1553bc_minor;
0054 struct gr1553bc_minor_cfg;
0055 struct gr1553bc_major_cfg;
0056
0057 #ifdef __cplusplus
0058 }
0059 #endif
0060
0061 #include <stdint.h>
0062 #include "gr1553bc_list.h"
0063
0064 #ifdef __cplusplus
0065 extern "C" {
0066 #endif
0067
0068 /* Register GR1553B driver needed by BC driver */
0069 extern void gr1553bc_register(void);
0070
0071 /* A BC descriptor accessed as is */
0072 struct gr1553bc_bd_raw {
0073     volatile uint32_t words[4];
0074 };
0075
0076 /* A BC descriptor accessed as a transfer descriptor */
0077 struct gr1553bc_bd_tr {
0078     volatile uint32_t settings[2];
0079     volatile uint32_t dptr;
0080     volatile uint32_t status;
0081 };
0082
0083 /* A BC descriptor accessed as a conditional descriptor */
0084 struct gr1553bc_bd_cond {
0085     volatile uint32_t cond;
0086     volatile uint32_t bdptr;
0087     volatile uint32_t padding[2];
0088 };
0089
0090 /* A BC descriptor accessed any way */
0091 union gr1553bc_bd {
0092     struct gr1553bc_bd_raw raw;
0093     struct gr1553bc_bd_tr tr;
0094     struct gr1553bc_bd_cond cond;
0095 };
0096
0097 /* Current state of the BC hardware */
0098 struct gr1553bc_status {
0099     unsigned int status;
0100     unsigned int time;
0101 };
0102
0103 #define KEEP_TIMESLOT 0x10
0104 /* Initialize a BC descriptor. The words written is controllable by
0105  * the flags argument.
0106  *
0107  * flags:
0108  *  bit[N=0..3]: 1 = set BD wordN according to argument wordN,
0109  *               0 = do not modify BD wordN
0110  *
0111  *  If bit KEEP_TIMESLOT is set the time slot of word0 is preserved,
0112  *  this bit only have an affect when the descriptor is a transfer
0113  *  descriptor.
0114  */
0115 extern void gr1553bc_bd_init(
0116     union gr1553bc_bd *bd,
0117     unsigned int flags,
0118     uint32_t word0,
0119     uint32_t word1,
0120     uint32_t word2,
0121     uint32_t word3
0122     );
0123
0124 /* Initialize a Transfer descriptor
0125  *
0126  * Arguments:
0127  *  struct gr1553bc_bd_tr *bd
0128  *  uint32_t setting0
0129  *  uint32_t setting1
0130  *  uint32_t data
0131  *  uint32_t status
0132  */
0133 #define gr1553bc_bd_tr_init(bd, set0, set1, data, status) \
0134         gr1553bc_bd_init((union gr1553bc_bd *)bd,\
0135                     0xf, set0, set1, data, status)
0136 /* Initializa a Condition descriptor
0137  *
0138  * Arguments:
0139  *  struct gr1553bc_bd_cond *bd
0140  *  uint32_t cond
0141  *  uint32_t jump_adr
0142  */
0143 #define gr1553bc_bd_cond_init(bd, cond, jump_adr) \
0144         gr1553bc_bd_init((union gr1553bc_bd *)bd, \
0145                     0xf, cond, jump_adr, 0, 0)
0146
0147 /* Size of a descriptor */
0148 #define GR1553BC_BD_SIZE sizeof(struct gr1553bc_bd_raw)
0149
0150 /* Alignment of a descriptor */
0151 #define GR1553BC_BD_ALIGN 16
0152
0153 /* End of list marker */
0154 #define GR1553BC_TR_EOL 0x80ffffff
0155
0156 #define GR1553BC_BD_TYPE    0x80000000
0157
0158 /* Condition descriptor bits */
0159 #define GR1553BC_UNCOND_JMP 0x820000ff
0160 #define GR1553BC_UNCOND_IRQ 0x860000ff
0161 #define GR1553BC_UNCOND_NOJMP   0x82000000
0162
0163 /* Transfer descriptor bits */
0164 #define GR1553BC_TR_DUMMY_0 0x00000000
0165 #define GR1553BC_TR_DUMMY_1 0x80000000
0166
0167 #define GR1553BC_TR_TIME    0x0000ffff
0168
0169 #define GR1553BC_TR_EXTTRIG 0x40000000
0170
0171 /* Take a GR1553BC hardware device identified by instance index (minor).
0172  * A pointer is returned that is used internally by the GR1553BC
0173  * driver, it is used as an input paramter 'bc' to all other
0174  * functions that manipulate the hardware.
0175  */
0176 extern void *gr1553bc_open(int minor);
0177
0178 extern void gr1553bc_close(void *bc);
0179
0180 /* Stores Current Major/Minor frame number and the Slot number executing
0181  * into the location indicated by 'mid'. There may be two lists executing
0182  * in "parallel", the 'async' argument select for which list the MID is
0183  * looked up, the Syncronous (async=0) list or the Asynchronous (async=1)
0184  * list.
0185  *
0186  */
0187 extern int gr1553bc_indication(void *bc, int async, int *mid);
0188
0189 /* Trigger external time sync by writing to the BC action register.
0190  * This may be good for debugging or if the time management is
0191  * implemented in software.
0192  *
0193  * if trig=0 the external trigger memory is cleared.
0194  * if trig!=0 the external trigger memory is set.
0195  */
0196 extern void gr1553bc_ext_trig(void *bc, int trig);
0197
0198 /* Configure the GR1553BC driver */
0199 /*extern int gr1553bc_config(struct gr1553bc_config *cfg);*/
0200
0201 /* Start major frame processing. At least one list pointer must be
0202  * non-zero to affect BC operation. The BC communication is enabled
0203  * depending on list and Interrupts are enabled. This function can
0204  * be called multiple times.
0205  *
0206  * If a list is already executing it will be replaced with the new
0207  * list.
0208  *
0209  * list        - Schedule Transfer List
0210  * list_async  - Asynchronous list
0211  */
0212 extern int gr1553bc_start
0213     (
0214     void *bc,
0215     struct gr1553bc_list *list,
0216     struct gr1553bc_list *list_async
0217     );
0218
0219 /* Pause GR1553B BC scheduled transfers.
0220  *
0221  * Does not affect asynchronous operation.
0222  */
0223 extern int gr1553bc_pause(void *bc);
0224
0225 /* Restart GR1553B BC scheduled transfers, after being paused
0226  *
0227  * Does not affect asynchronous operation.
0228  */
0229 extern int gr1553bc_restart(void *bc);
0230
0231 /* Stop BC transmission.
0232  *
0233  * OPTIONS
0234  *   bit0 - 1=STOP schedule list
0235  *   bit1 - 1=STOP asynchronous list
0236  */
0237 extern int gr1553bc_stop(void *bc, int options);
0238
0239 /* Standard IRQ function setup. IRQ can be generated by condition descriptors
0240  * or by transfer descriptors or by errors.
0241  *
0242  * Condition descriptors are inserted into the list by user, each condition
0243  * may have a custom function and data assigned to it, see
0244  * gr1553bc_slot_irq_prepare(). IRQs generated by condition descriptors are
0245  * not handled by this function.
0246  *
0247  * Transfer descriptors can generate IRQ if enabled by user.
0248  *
0249  * IRQs generated by transfer descriptors or by BC errors (DMA error etc.)
0250  * is handled by this standard ISR handler.
0251  */
0252 extern int gr1553bc_irq_setup
0253     (
0254     void *bc,
0255     bcirq_func_t func,
0256     void *data
0257     );
0258
0259 /* Get Current BC hardware state/status. The Status is stored into the
0260  * area pointed to by status. See "struct gr1553bc_status" for more
0261  * info.
0262  */
0263 extern void gr1553bc_status(void *bc, struct gr1553bc_status *status);
0264
0265 #ifdef __cplusplus
0266 }
0267 #endif
0268
0269 #endif /* __GR1553BC_H__ */