source: rtems/c/src/lib/libbsp/sparc/shared/include/gr1553rt.h @ 4a7d1026

4.11
Last change on this file since 4a7d1026 was 4a7d1026, checked in by Daniel Hellstrom <daniel@…>, on Apr 13, 2015 at 8:25:52 AM

sparc bsps: updated license to rtems.org

  • Property mode set to 100644
File size: 14.2 KB
Line 
1/*  GR1553B RT driver
2 *
3 *  COPYRIGHT (c) 2010.
4 *  Cobham Gaisler AB.
5 *
6 *  The license and distribution terms for this file may be
7 *  found in the file LICENSE in this distribution or at
8 *  http://www.rtems.org/license/LICENSE.
9 */
10
11#ifndef __GR1553RT_H__
12#define __GR1553RT_H__
13
14/* CONFIG OPTION: Maximum number of LIST IDs supported.
15 *                There are two lists per RT subaddress, one for RX one
16 *                for TX.
17 */
18#define RTLISTID_MAX 64
19
20/* CONFIG OPTION: Maximum number of Interrupt handlers per device supported
21 * max is 256 supported, and minimum is 1.
22 */
23#define RTISR_MAX 64
24
25/* CONFIG OPTION: Maximum number of transfer (RX/TX) descriptors supported.
26 *
27 * Set this option to zero to allow flexible number of descriptors,
28 * requires dynamically allocation of driver structures.
29 */
30/*#define RTBD_MAX 4096*/
31#define RTBD_MAX 0
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37/* Register GR1553B driver needed by RT driver */
38extern void gr1553rt_register(void);
39
40struct gr1553rt_list;
41
42/* Descriptor read/written by hardware.
43 *
44 * Must be aligned to 16 byte boundary
45 */
46struct gr1553rt_bd {
47        volatile unsigned int   ctrl;   /* 0x00 Control/Status word */
48        volatile unsigned int   dptr;   /* 0x04 Data Pointer */
49        volatile unsigned int   next;   /* 0x08 Next Descriptor in list */
50        volatile unsigned int   unused; /* 0x0C UNUSED BY HARDWARE */
51};
52
53/* Sub address table entry, the hardware access */
54struct gr1553rt_sa {
55        volatile unsigned int ctrl;     /* 0x00 SUBADDRESS CONTROL WORD */
56        volatile unsigned int txptr;    /* 0x04 TRANSMIT BD POINTER */
57        volatile unsigned int rxptr;    /* 0x08 RECEIVE BD POINTER */
58        volatile unsigned int unused;   /* 0x0C UNUSED BY HARDWARE */
59};
60
61/* Configuration of a RT-SubAddress-List */
62struct gr1553rt_list_cfg {
63        unsigned int bd_cnt;            /* Number of hw-descriptors in list */
64};
65
66/* A TX or RX subaddress descriptor list */
67struct gr1553rt_list {
68        short listid;                   /* ID/NUMBER of List. -1 unassigned */
69        short subadr;                   /* SubAddress. -1 when not scheduled */
70        void *rt;                       /* Scheduled on Device */
71        struct gr1553rt_list_cfg *cfg;  /* List configuration */
72        int bd_cnt;                     /* Number of Descriptors */
73
74        /* !!Must be last in data structure!!
75         * !!Array must at least be of length bd_cnt!!
76         */
77        unsigned short bds[1];          /* Array of BDIDs, -1 unused/end */
78};
79
80/* GR1553B-RT Driver configuration options used when calling gr1553rt_config().
81 *
82 * Note that if not custom addresses are given the driver will dynamically
83 *      allocate memory for buffers.
84 * Note that if custom addresses with the LSB set, the address will be
85 *      interpreted as a address accessible by hardware, and translated
86 *      into an address used by CPU.
87 */
88struct gr1553rt_cfg {
89        unsigned char rtaddress;        /* RT Address 0..30 */
90
91        /*** MODE CODE CONFIG ***/
92        unsigned int modecode;          /* Mode codes enable/disable/IRQ/EV-Log.
93                                         * Each modecode has a 2-bit cfg field.
94                                         * See Mode Code Control Register in
95                                         * hardware manual.
96                                         */
97
98        /*** TIME CONFIG ***/
99        unsigned short time_res;        /* Time tag resolution in us */
100
101        /*** SUBADDRESS TABLE CONFIG ***/
102        void *satab_buffer;             /* Optional Custom buffer. Must be
103                                         * At least 16*32 bytes, and be aligned
104                                         * to 10-bit (1KB) boundary. Set to NULL
105                                         * to make driver allocate buffer.
106                                         */
107
108        /*** EVENT LOG CONFIG ***/
109        void *evlog_buffer;             /* Optional Custom buffer */
110        int evlog_size;                 /* Length, must be a multiple of 2.
111                                         * If set to ZERO event log is disabled
112                                         */
113
114        /*** TRANSFER DESCRIPTOR CONFIG ***/
115        int bd_count;                   /* Number of transfer descriptors shared
116                                         * by all RX/TX sub-addresses */
117        void *bd_buffer;                /* Optional Custom descriptor area.
118                                         * Must hold bd_count*32 bytes.
119                                         * If NULL, descriptors will be         
120                                         * allocated dynamically. */
121};
122
123/* GR1553B-RT status indication, copied from the RT registers and stored
124 * here. Used when calling the gr1553rt_status() function.
125 */
126struct gr1553rt_status {
127        unsigned int status;            /* RT Status word */
128        unsigned int bus_status;        /* BUS Status */
129        unsigned short synctime;        /* Time Tag of last sync with data */
130        unsigned short syncword;        /* Data of last mode code synchronize
131                                         * with data. */
132        unsigned short time_res;        /* Time resolution (set by config) */
133        unsigned short time;            /* Current Time Tag */
134};
135
136/* ISR callback definition for ERRORs detected in the GR1553B-RT interrupt
137 * handler.
138 *
139 * \param err    Inidicate Error type. The IRQ flag register bit mask:
140 *                 Bit 9  - RT DMA ERROR
141 *                 Bit 10 - RT Table access error
142 * \param data   Custom data assigned by user
143 */
144typedef void (*gr1553rt_irqerr_t)(int err, void *data);
145
146/* ISR callback definition for modecodes that are configured to generate
147 * an IRQ. The callback is called from within the GR1553B-RT interrupt
148 * handler.
149 *
150 * \param mcode  Mode code that caused this IRQ
151 * \param entry  The raw Eventlog Entry
152 * \param data   Custom data assigned by user
153 */
154typedef void (*gr1553rt_irqmc_t)(int mcode, unsigned int entry, void *data);
155
156/* Transfer ISR callback definition. Called from GR1553B-RT interrupt handler
157 * when an interrupt has been generated and a event logged due to a 1553
158 * transfer to this RT.
159 *
160 * \param list     List (Subaddress/TransferType) that caused IRQ
161 * \param entry    The raw Eventlog Entry
162 * \param bd_next  Next Descriptor-entry index in the list (Subaddress/tr-type)
163 *                 This can be used to process all descriptors upto entry_next.
164 * \param data     Custom data assigned by user
165 */
166typedef void (*gr1553rt_irq_t)(
167        struct gr1553rt_list *list, 
168        unsigned int entry,
169        int bd_next,
170        void *data
171        );
172
173/* Configure a list according to configuration. Assign the list
174 * to a device, however not to a RT sub address yet. The rt
175 * is stored within list.
176 *
177 * \param rt       RT Device driver identification, stored within list.
178 * \param list     The list to configure
179 * \param cfg      Configuration for list. Pointer to configuration is
180 *                 stored within list for later use.
181 */
182extern int gr1553rt_list_init
183        (
184        void *rt,
185        struct gr1553rt_list **plist,
186        struct gr1553rt_list_cfg *cfg
187        );
188
189/* Assign an Error Interrupt handler. Before the handler is called the
190 * RT hardware is stopped/disabled. The handler is optional, if not assigned
191 * the ISR will still stop the RT upon error.
192 *
193 * Errors detected by the interrupt handler:
194 *  - DMA error
195 *  - Subaddress table access error
196 *
197 * \param func     ISR called when an error causes an interrupt.
198 * \param data     Custom data given as an argument when calling ISR
199 */
200extern int gr1553rt_irq_err
201        (
202        void *rt,
203        gr1553rt_irqerr_t func,
204        void *data
205        );
206
207/* Assign a ModeCode Interrupt handler callback. Called when a 1553 modecode
208 * transfer is logged and cause an IRQ. The modecode IRQ generation is
209 * configured from "struct gr1553rt_cfg" when calling gr1553rt_config().
210 *
211 * \param func     ISR called when a modecode causes an interrupt.
212 * \param data     Custom data given as an argument when calling ISR
213 */
214extern int gr1553rt_irq_mc
215        (
216        void *rt,
217        gr1553rt_irqmc_t func,
218        void *data
219        );
220
221/* Assign transfer interrupt handler callback. Called when a RX or TX
222 * transfer is logged and cause an interrupt, the function is called
223 * from the GR1553B-RT driver's ISR, in interrupt context.
224 *
225 * The callback can be installed per subaddress and transfer type.
226 * Subaddress 0 and 31 are not valid (gr1553rt_irq_mc() for modecodes).
227 *
228 * \param subadr   Select subaddress (1-30)
229 * \param tx       1=TX subaddress, 0=RX subaddress
230 * \param func     ISR called when subaddress of spcified transfer type
231 *                 causes an interrupt.
232 * \param data     Custom data given as an argument when calling ISR
233 */
234extern int gr1553rt_irq_sa
235        (
236        void *rt,
237        int subadr,
238        int tx,
239        gr1553rt_irq_t func,
240        void *data
241        );
242
243#define GR1553RT_BD_FLAGS_IRQEN (1<<30)
244/* Initialize a descriptor entry in a list. This is typically done
245 * prior to scheduling the list.
246 *
247 * \param entry_no  Entry number in list (descriptor index in list)
248 * \param flags     Enable IRQ when descriptor is accessed by setting
249 *                  argument GR1553RT_BD_FLAGS_IRQEN. Enabling IRQ on a
250 *                  descriptor basis will override SA-table IRQ config.
251 * \param dptr      Data Pointer to RX or TX operation. The LSB indicate
252 *                  if the address must be translated into Hardware address
253 *                  - this is useful when a buffer close to CPU is used
254 *                  as a data pointer and the RT core is located over PCI.
255 * \param next      Next Entry in list. Set to 0xffff for end of list. Set
256 *                  0xfffe for next entry in list, wrap around to entry
257 *                  zero if entry_no is last descriptor in list (circular).
258 */
259extern int gr1553rt_bd_init(
260        struct gr1553rt_list *list,
261        unsigned short entry_no,
262        unsigned int flags,
263        uint16_t *dptr,
264        unsigned short next
265        );
266
267/* Manipulate/Read Control/Status and Data Pointer words of a buffer descriptor.
268 * If status is zero, the control/status word is accessed. If dptr is non-zero
269 * the data pointer word is accessed.
270 *
271 * \param list       The list that the descriptor is located at
272 *
273 * \param entry_no   The descriptor number accessed
274 *
275 * \param status     IN/OUT. If zero no effect. If pointer is non-zero the
276 *                   value pointed to:
277 *                   IN: Written to Control/Status
278 *                   OUT: the value of the Control/Status word before writing.
279 *
280 * \param dptr       IN/OUT. If zero no effect. If pointer is non-zero, the
281 *                   value pointed to:
282 *                   IN: non-zero: Descriptor data pointer will be updated with
283 *                       this value. Note that the LSB indicate if the address
284 *                       must be translated into hardware-aware address.
285 *                   OUT: The old data pointer is stored here.
286 */
287extern int gr1553rt_bd_update(
288        struct gr1553rt_list *list,
289        int entry_no,
290        unsigned int *status,
291        uint16_t **dptr
292        );
293
294/* Get the next/current descriptor processed of a RT sub-address.
295 *
296 * \param subadr  RT Subaddress
297 * \param txeno   Pointer to where TX descriptor number is stored.
298 * \param rxeno   Pointer to where RX descriptor number is stored.
299 */
300extern int gr1553rt_indication(void *rt, int subadr, int *txeno, int *rxeno);
301
302/* Take a GR1553RT hardware device identified by minor.
303 * A pointer is returned that is used internally by the GR1553RT
304 * driver, it is used as an input parameter 'rt' to all other
305 * functions that manipulate the hardware.
306 *
307 * This function initializes the RT hardware to a stopped/disable level.
308 */
309extern void *gr1553rt_open(int minor);
310
311/* Close and stop/disable the RT hardware. */
312extern void gr1553rt_close(void *rt);
313
314/* Configure the RT. The RT device must be configured once before
315 * started. A started RT device can not be configured.
316 *
317 * \param rt    The RT to configure
318 * \param cfg   Configuration parameters
319 */
320extern int gr1553rt_config(void *rt, struct gr1553rt_cfg *cfg);
321
322/* Schedule a RX or TX list on a sub address. If a list has already been
323 * schduled on the subaddress and on the same transfer type (RX/TX), the
324 * old list is replaced with the list given here.
325 *
326 * \param subadr   Subaddress to schedule list on
327 * \param tx       Subaddress transfer type: 1=TX, 0=RX
328 * \param list     Preconfigued RT list scheduled
329 */
330extern void gr1553rt_sa_schedule(
331        void *rt,
332        int subadr,
333        int tx,
334        struct gr1553rt_list *list
335        );
336
337/* Set SubAdress options. One may for example Enable or Disable a sub
338 * address RX and/or TX. See hardware manual for SA-Table configuration
339 * options.
340 *
341 * \param subadr   SubAddress to configure
342 * \param mask     Bit mask of option-bits written to subaddress config
343 * \param options  The new options written to subaddress config.
344 *
345 */
346extern void gr1553rt_sa_setopts(
347        void *rt,
348        int subadr,
349        unsigned int mask,
350        unsigned int options
351        );
352
353/* Get The Subaddress and transfer type of a scheduled list. Normally the
354 * application knows which subaddress the list is for.
355 *
356 * \param list     List to lookup information for
357 * \param subadr   Pointer to where the subaddress is stored
358 * \param tx       Transfer type is stored here. 1=TX, 0=RX.
359 */
360extern void gr1553rt_list_sa(
361        struct gr1553rt_list *list,
362        int *subadr,
363        int *tx
364        );
365
366/* Start RT Communication
367 *
368 * Interrupts will be enabled. The RT enabled and the "RT-run-time"
369 * part of the API will be opened for the user and parts that need the
370 * RT to be stopped are no longer available. After the RT has been
371 * started the configuration function can not be called.
372 */
373extern int gr1553rt_start(void *rt);
374
375/* Get Status of the RT core. See data structure gr1553rt_status for more
376 * information about the result. It can be used to read out:
377 *  - time information
378 *  - sync information
379 *  - bus & RT status
380 *
381 * \param status   Pointer to where the status words will be stored. They
382 *                 are stored according to the gr1553rt_status data structure.
383 */
384extern void gr1553rt_status(void *rt, struct gr1553rt_status *status);
385
386/* Stop RT communication. Only possible to stop an already started RT device.
387 * Interrupts are disabled and the RT Enable bit cleared.
388 */
389extern void gr1553rt_stop(void *rt);
390
391/* Set RT vector and/or bit word.
392 *
393 *  - Vector Word is used in response to "Transmit vector word" BC commands
394 *  - Bit Word is used in response to "Transmit bit word" BC commands
395 *
396 *
397 * \param mask     Bit-Mask, bits that are 1 will result in that bit in the
398 *                 words register being overwritten with the value of words
399 * \param words    Bits 31..16: Bit Word. Bits 15..0: Vector Word.
400 *
401 * Operation:
402 *  hw_words = (hw_words & ~mask) | (words & mask)
403 */
404extern void gr1553rt_set_vecword(
405        void *rt,
406        unsigned int mask,
407        unsigned int words
408        );
409
410/* Set selectable bits of the "Bus Status Register". The bits written
411 * is determined by the "mask" bit-mask. Operation:
412 *
413 * bus_status = (bus_status & ~mask) | (sts & mask)
414 *
415 */
416extern void gr1553rt_set_bussts(void *rt, unsigned int mask, unsigned int sts);
417
418/* Read up to MAX number of entries in eventlog log.
419 *
420 * \param dst   Destination address for event log entries
421 * \param max   Maximal number of event log entries that an be stored into dst
422 *
423 * Return
424 *  negative   Failure
425 *  zero       No entries available at the moment
426 *  positive   Number of entries copied into dst
427 */
428extern int gr1553rt_evlog_read(void *rt, unsigned int *dst, int max);
429
430#ifdef __cplusplus
431}
432#endif
433
434#endif
Note: See TracBrowser for help on using the repository browser.