source: rtems/bsps/m68k/include/mcf548x/MCD_dma.h @ d7d66d7

5
Last change on this file since d7d66d7 was 2afb22b, checked in by Chris Johns <chrisj@…>, on Dec 23, 2017 at 7:18:56 AM

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 11.5 KB
Line 
1/*
2 * File:        MCD_dma.h
3 * Purpose:     Main header file for multi-channel DMA API.
4 *
5 * Notes:
6 */
7#ifndef _MCD_API_H
8#define _MCD_API_H
9
10/*
11 * Turn Execution Unit tasks ON (#define) or OFF (#undef)
12 */
13#define MCD_INCLUDE_EU
14
15/*
16 * Number of DMA channels
17 */
18#define NCHANNELS 16
19
20/*
21 * Total number of variants
22 */
23#ifdef MCD_INCLUDE_EU
24#define NUMOFVARIANTS   6
25#else
26#define NUMOFVARIANTS   4
27#endif
28
29/*
30 * Define sizes of the various tables
31 */
32#define TASK_TABLE_SIZE     (NCHANNELS*32)
33#define VAR_TAB_SIZE        (128)
34#define CONTEXT_SAVE_SIZE   (128)
35#define FUNCDESC_TAB_SIZE   (256)
36
37#ifdef MCD_INCLUDE_EU
38#define FUNCDESC_TAB_NUM    16
39#else
40#define FUNCDESC_TAB_NUM    1
41#endif
42
43
44#ifndef DEFINESONLY
45
46/*
47 * Portability typedefs
48 */
49typedef int s32;
50typedef unsigned int u32;
51typedef short s16;
52typedef unsigned short u16;
53typedef char s8;
54typedef unsigned char u8;
55
56/*
57 * These structures represent the internal registers of the
58 * multi-channel DMA
59 */
60struct dmaRegs_s {
61   u32 taskbar;         /* task table base address register */
62   u32 currPtr;
63   u32 endPtr;
64   u32 varTablePtr;
65   u16 dma_rsvd0;
66   u16 ptdControl;      /* ptd control */
67   u32 intPending;      /* interrupt pending register */
68   u32 intMask;         /* interrupt mask register */
69   u16 taskControl[16]; /* task control registers */
70   u8  priority[32];    /* priority registers */
71   u32 initiatorMux;    /* initiator mux control */
72   u32 taskSize0;       /* task size control register 0. */
73   u32 taskSize1;       /* task size control register 1. */
74   u32 dma_rsvd1;       /* reserved */
75   u32 dma_rsvd2;       /* reserved */
76   u32 debugComp1;      /* debug comparator 1 */
77   u32 debugComp2;      /* debug comparator 2 */
78   u32 debugControl;    /* debug control */
79   u32 debugStatus;     /* debug status */
80   u32 ptdDebug;        /* priority task decode debug */
81   u32 dma_rsvd3[31];   /* reserved */
82};
83typedef volatile struct dmaRegs_s dmaRegs;
84
85#endif
86
87/*
88 * PTD contrl reg bits
89 */
90#define PTD_CTL_TSK_PRI         0x8000
91#define PTD_CTL_COMM_PREFETCH   0x0001
92
93/*
94 * Task Control reg bits and field masks
95 */
96#define TASK_CTL_EN             0x8000
97#define TASK_CTL_VALID          0x4000
98#define TASK_CTL_ALWAYS         0x2000
99#define TASK_CTL_INIT_MASK      0x1f00
100#define TASK_CTL_ASTRT          0x0080
101#define TASK_CTL_HIPRITSKEN     0x0040
102#define TASK_CTL_HLDINITNUM     0x0020
103#define TASK_CTL_ASTSKNUM_MASK  0x000f
104
105/*
106 * Priority reg bits and field masks
107 */
108#define PRIORITY_HLD            0x80
109#define PRIORITY_PRI_MASK       0x07
110
111/*
112 * Debug Control reg bits and field masks
113 */
114#define DBG_CTL_BLOCK_TASKS_MASK    0xffff0000
115#define DBG_CTL_AUTO_ARM            0x00008000
116#define DBG_CTL_BREAK               0x00004000
117#define DBG_CTL_COMP1_TYP_MASK      0x00003800
118#define DBG_CTL_COMP2_TYP_MASK      0x00000070
119#define DBG_CTL_EXT_BREAK           0x00000004
120#define DBG_CTL_INT_BREAK           0x00000002
121
122/*
123 * PTD Debug reg selector addresses
124 * This reg must be written with a value to show the contents of
125 * one of the desired internal register.
126 */
127#define PTD_DBG_REQ             0x00 /* shows the state of 31 initiators */
128#define PTD_DBG_TSK_VLD_INIT    0x01 /* shows which 16 tasks are valid and
129                                        have initiators asserted */
130
131
132/*
133 * General return values
134 */
135#define MCD_OK                   0
136#define MCD_ERROR               -1
137#define MCD_TABLE_UNALIGNED     -2
138#define MCD_CHANNEL_INVALID     -3
139
140/*
141 * MCD_initDma input flags
142 */
143#define MCD_RELOC_TASKS         0x00000001
144#define MCD_NO_RELOC_TASKS      0x00000000
145#define MCD_COMM_PREFETCH_EN    0x00000002  /* Commbus Prefetching - MCF547x/548x ONLY */
146
147/*
148 * MCD_dmaStatus Status Values for each channel
149 */
150#define MCD_NO_DMA  1 /* No DMA has been requested since reset */
151#define MCD_IDLE    2 /* DMA active, but the initiator is currently inactive */
152#define MCD_RUNNING 3 /* DMA active, and the initiator is currently active */
153#define MCD_PAUSED  4 /* DMA active but it is currently paused */
154#define MCD_HALTED  5 /* the most recent DMA has been killed with MCD_killTask() */
155#define MCD_DONE    6 /* the most recent DMA has completed. */
156
157
158/*
159 * MCD_startDma parameter defines
160 */
161
162/*
163 * Constants for the funcDesc parameter
164 */
165/* Byte swapping: */
166#define MCD_NO_BYTE_SWAP    0x00045670  /* to disable byte swapping. */
167#define MCD_BYTE_REVERSE    0x00076540  /* to reverse the bytes of each u32 of the DMAed data. */
168#define MCD_U16_REVERSE     0x00067450  /* to reverse the 16-bit halves of
169                                           each 32-bit data value being DMAed.*/
170#define MCD_U16_BYTE_REVERSE    0x00054760 /* to reverse the byte halves of each
171                                            16-bit half of each 32-bit data value DMAed */
172#define MCD_NO_BIT_REV  0x00000000  /* do not reverse the bits of each byte DMAed. */
173#define MCD_BIT_REV     0x00088880  /* reverse the bits of each byte DMAed */
174/* CRCing: */
175#define MCD_CRC16       0xc0100000  /* to perform CRC-16 on DMAed data. */
176#define MCD_CRCCCITT    0xc0200000  /* to perform CRC-CCITT on DMAed data. */
177#define MCD_CRC32       0xc0300000  /* to perform CRC-32 on DMAed data. */
178#define MCD_CSUMINET    0xc0400000  /* to perform internet checksums on DMAed data.*/
179#define MCD_NO_CSUM     0xa0000000  /* to perform no checksumming. */
180
181#define MCD_FUNC_NOEU1 (MCD_NO_BYTE_SWAP | MCD_NO_BIT_REV | MCD_NO_CSUM)
182#define MCD_FUNC_NOEU2 (MCD_NO_BYTE_SWAP | MCD_NO_CSUM)
183
184/*
185 * Constants for the flags parameter
186 */
187#define MCD_TT_FLAGS_RL   0x00000001 /* Read line */
188#define MCD_TT_FLAGS_CW   0x00000002 /* Combine Writes */
189#define MCD_TT_FLAGS_SP   0x00000004 /* Speculative prefetch(XLB) MCF547x/548x ONLY  */
190#define MCD_TT_FLAGS_MASK 0x000000ff
191#define MCD_TT_FLAGS_DEF  (MCD_TT_FLAGS_RL | MCD_TT_FLAGS_CW)
192
193#define MCD_SINGLE_DMA  0x00000100 /* Unchained DMA */
194#define MCD_CHAIN_DMA              /* TBD */
195#define MCD_EU_DMA                 /* TBD */
196#define MCD_FECTX_DMA   0x00001000 /* FEC TX ring DMA */
197#define MCD_FECRX_DMA   0x00002000 /* FEC RX ring DMA */
198
199
200/* these flags are valid for MCD_startDma and the chained buffer descriptors */
201#define MCD_BUF_READY   0x80000000 /* indicates that this buffer is now under the DMA's control */
202#define MCD_WRAP        0x20000000 /* to tell the FEC Dmas to wrap to the first BD */
203#define MCD_INTERRUPT   0x10000000 /* to generate an interrupt after completion of the DMA. */
204#define MCD_END_FRAME   0x08000000 /* tell the DMA to end the frame when transferring
205                                      last byte of data in buffer */
206#define MCD_CRC_RESTART 0x40000000 /* to empty out the accumulated checksum
207                                      prior to performing the DMA. */
208
209/* Defines for the FEC buffer descriptor control/status word*/
210#define MCD_FEC_BUF_READY   0x8000
211#define MCD_FEC_WRAP        0x2000
212#define MCD_FEC_INTERRUPT   0x1000
213#define MCD_FEC_END_FRAME   0x0800
214
215
216/*
217 * Defines for general intuitiveness
218 */
219
220#define MCD_TRUE  1
221#define MCD_FALSE 0
222
223/*
224 * Three different cases for destination and source.
225 */
226#define MINUS1          -1
227#define ZERO            0
228#define PLUS1           1
229
230#ifndef DEFINESONLY
231
232/* Task Table Entry struct*/
233typedef struct {
234    u32 TDTstart;   /* task descriptor table start */
235    u32 TDTend;     /* task descriptor table end */
236    u32 varTab;     /* variable table start */
237    u32 FDTandFlags;    /* function descriptor table start and flags */
238    volatile u32 descAddrAndStatus;
239    volatile u32 modifiedVarTab;
240    u32 contextSaveSpace;   /* context save space start */
241    u32 literalBases;
242} TaskTableEntry;
243
244
245/* Chained buffer descriptor */
246typedef volatile struct MCD_bufDesc_struct MCD_bufDesc;
247struct MCD_bufDesc_struct {
248   u32 flags;         /* flags describing the DMA */
249   u32 csumResult;    /* checksum from checksumming performed since last checksum reset */
250   s8  *srcAddr;      /* the address to move data from */
251   s8  *destAddr;     /* the address to move data to */
252   s8  *lastDestAddr; /* the last address written to */
253   u32 dmaSize;       /* the number of bytes to transfer independent of the transfer size */
254   MCD_bufDesc *next; /* next buffer descriptor in chain */
255   u32 info;          /* private information about this descriptor;  DMA does not affect it */
256};
257
258/* Progress Query struct */
259typedef volatile struct MCD_XferProg_struct {
260   s8 *lastSrcAddr;         /* the most-recent or last, post-increment source address */
261   s8 *lastDestAddr;        /* the most-recent or last, post-increment destination address */
262   u32  dmaSize;            /* the amount of data transferred for the current buffer */
263   MCD_bufDesc *currBufDesc;/* pointer to the current buffer descriptor being DMAed */
264} MCD_XferProg;
265
266
267/* FEC buffer descriptor */
268typedef volatile struct MCD_bufDescFec_struct {
269    u16 statCtrl;
270    u16 length;
271    u32 dataPointer;
272} MCD_bufDescFec;
273
274
275/*************************************************************************/
276/*
277 * API function Prototypes  - see MCD_dmaApi.c for further notes
278 */
279
280/*
281 * MCD_startDma starts a particular kind of DMA .
282 */
283int MCD_startDma (
284   int channel,   /* the channel on which to run the DMA */
285   s8  *srcAddr,  /* the address to move data from, or buffer-descriptor address */
286   s16 srcIncr,   /* the amount to increment the source address per transfer */
287   s8  *destAddr, /* the address to move data to */
288   s16 destIncr,  /* the amount to increment the destination address per transfer */
289   u32 dmaSize,   /* the number of bytes to transfer independent of the transfer size */
290   u32 xferSize,  /* the number bytes in of each data movement (1, 2, or 4) */
291   u32 initiator, /* what device initiates the DMA */
292   int priority,  /* priority of the DMA */
293   u32 flags,     /* flags describing the DMA */
294   u32 funcDesc   /* a description of byte swapping, bit swapping, and CRC actions */
295);
296
297/*
298 * MCD_initDma() initializes the DMA API by setting up a pointer to the DMA
299 * registers, relocating and creating the appropriate task structures, and
300 * setting up some global settings
301 */
302int MCD_initDma (dmaRegs *sDmaBarAddr, void *taskTableDest, u32 flags);
303
304/*
305 * MCD_dmaStatus() returns the status of the DMA on the requested channel.
306 */
307int MCD_dmaStatus (int channel);
308
309/*
310 * MCD_XferProgrQuery() returns progress of DMA on requested channel
311 */
312int MCD_XferProgrQuery (int channel, MCD_XferProg *progRep);
313
314/*
315 * MCD_killDma() halts the DMA on the requested channel, without any
316 * intention of resuming the DMA.
317 */
318int MCD_killDma (int channel);
319
320/*
321 * MCD_continDma() continues a DMA which as stopped due to encountering an
322 * unready buffer descriptor.
323 */
324int MCD_continDma (int channel);
325
326/*
327 * MCD_pauseDma() pauses the DMA on the given channel ( if any DMA is
328 * running on that channel).
329 */
330int MCD_pauseDma (int channel);
331
332/*
333 * MCD_resumeDma() resumes the DMA on a given channel (if any DMA is
334 * running on that channel).
335 */
336int MCD_resumeDma (int channel);
337
338/*
339 * MCD_csumQuery provides the checksum/CRC after performing a non-chained DMA
340 */
341int MCD_csumQuery (int channel, u32 *csum);
342
343/*
344 * MCD_getCodeSize provides the packed size required by the microcoded task
345 * and structures.
346 */
347int MCD_getCodeSize(void);
348
349/*
350 * MCD_getVersion provides a pointer to a version string and returns a
351 * version number.
352 */
353int MCD_getVersion(char **longVersion);
354
355/* macro for setting a location in the variable table */
356#define MCD_SET_VAR(taskTab,idx,value) ((u32 *)(taskTab)->varTab)[idx] = value
357   /* Note that MCD_SET_VAR() is invoked many times in firing up a DMA function,
358      so I'm avoiding surrounding it with "do {} while(0)" */
359
360#endif  /* DEFINESONLY */
361
362#endif /* _MCD_API_H */
Note: See TracBrowser for help on using the repository browser.