source: rtems/bsps/arm/altera-cyclone-v/include/bsp/alt_dma_program.h @ 9d41fca

5
Last change on this file since 9d41fca was 9d41fca, checked in by Sebastian Huber <sebastian.huber@…>, on 02/27/19 at 10:39:29

bsp/altera-cyclone-v: Adjust Doxygen file groups

Update #3707.
  • Property mode set to 100644
File size: 36.0 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup RTEMSBSPsARMCycVContrib
5 */
6
7/******************************************************************************
8 *
9 * Copyright 2013 Altera Corporation. All Rights Reserved.
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions are met:
13 *
14 * 1. Redistributions of source code must retain the above copyright notice,
15 * this list of conditions and the following disclaimer.
16 *
17 * 2. Redistributions in binary form must reproduce the above copyright notice,
18 * this list of conditions and the following disclaimer in the documentation
19 * and/or other materials provided with the distribution.
20 *
21 * 3. The name of the author may not be used to endorse or promote products
22 * derived from this software without specific prior written permission.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
25 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
26 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
27 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
28 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
29 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
32 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
33 * OF SUCH DAMAGE.
34 *
35 ******************************************************************************/
36
37#ifndef __ALT_DMA_PROGRAM_H__
38#define __ALT_DMA_PROGRAM_H__
39
40#include "hwlib.h"
41#include "alt_dma_common.h"
42
43#ifdef __cplusplus
44extern "C"
45{
46#endif  /* __cplusplus */
47
48/*!
49 * \addtogroup ALT_DMA_PRG DMA Controller Programming API
50 *
51 * This API provides functions for dynamically defining and assembling microcode
52 * programs for execution on the DMA controller.
53 *
54 * The microcode program assembly API provides users with the ability to develop
55 * highly optimized and tailored algorithms for data transfer between SoC FPGA
56 * IP blocks and/or system memory.
57 *
58 * The same microcode program assembly facilities are also used to implement the
59 * functions found in the HWLIB Common DMA Operations functional API.
60 *
61 * An ALT_DMA_PROGRAM_t structure is used to contain and assemble a DMA
62 * microcode program. The storage for an ALT_DMA_PROGRAM_t stucture is allocated
63 * from used specified system memory. Once a microcode program has been
64 * assembled in a ALT_DMA_PROGRAM_t it may be excecuted on a designated DMA
65 * channel thread. The microcode program may be rerun on any DMA channel thread
66 * whenever required as long as the integrity of the ALT_DMA_PROGRAM_t
67 * containing the program is maintained.
68 *
69 * @{
70 */
71
72/*!
73 * This preprocessor declares the DMA channel thread microcode instruction
74 * cache line width in bytes. It is recommended that the program buffers be
75 * sized to a multiple of the cache line size. This will allow for the most
76 * efficient microcode speed and space utilization.
77 */
78#define ALT_DMA_PROGRAM_CACHE_LINE_SIZE     (32)
79
80/*!
81 * This preprocessor declares the DMA channel thread microcode instruction
82 * cache line count. Thus the total size of the cache is the cache line size
83 * multipled by the cache line count. Programs larger than the cache size risk
84 * having a cache miss while executing.
85 */
86#define ALT_DMA_PROGRAM_CACHE_LINE_COUNT    (16)
87
88/*!
89 * This preprocessor definition determines the size of the program buffer
90 * within the ALT_DMA_PROGRAM_t structure. This size should provide adequate
91 * size for most DMA microcode programs. If calls within this API are
92 * reporting out of memory response codes, consider increasing the provisioned
93 * program buffersize.
94 *
95 * To specify another DMA microcode program buffer size, redefine the macro
96 * below by defining ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE to another size in
97 * your Makefile. It is recommended that the size be a multiple of the
98 * microcode engine cache line size. See ALT_DMA_PROGRAM_CACHE_LINE_SIZE for
99 * more information. The largest supported buffer size is 65536 bytes.
100 */
101#ifndef ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE
102#define ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE   (ALT_DMA_PROGRAM_CACHE_LINE_SIZE * ALT_DMA_PROGRAM_CACHE_LINE_COUNT)
103#endif
104
105/*!
106 * This type defines the structure used to assemble and contain a microcode
107 * program which can be executed by the DMA controller. The internal members
108 * are undocumented and should not be altered outside of this API.
109 */
110typedef struct ALT_DMA_PROGRAM_s
111{
112    uint32_t flag;
113
114    uint16_t buffer_start;
115    uint16_t code_size;
116
117    uint16_t loop0;
118    uint16_t loop1;
119
120    uint16_t sar;
121    uint16_t dar;
122
123    /*
124     * Add a little extra space so that regardless of where this structure
125     * sits in memory, a suitable start address can be aligned to the cache
126     * line stride while providing the requested buffer space.
127     */
128    uint8_t program[ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE +
129                    ALT_DMA_PROGRAM_CACHE_LINE_SIZE];
130}
131ALT_DMA_PROGRAM_t;
132
133/*!
134 * This type definition enumerates the DMA controller register names for use in
135 * microcode program definition.
136 */
137typedef enum ALT_DMA_PROGRAM_REG_e
138{
139    /*! Source Address Register */
140    ALT_DMA_PROGRAM_REG_SAR = 0x0,
141
142    /*! Destination Address Register */
143    ALT_DMA_PROGRAM_REG_DAR = 0x2,
144
145    /*! Channel Control Register */
146    ALT_DMA_PROGRAM_REG_CCR = 0x1
147}
148ALT_DMA_PROGRAM_REG_t;
149
150/*!
151 * This type definition enumerates the instruction modifier options available
152 * for use with selected DMA microcode instructions.
153 *
154 * The enumerations values are context dependent upon the instruction being
155 * modified.
156 *
157 * For the <b>DMALD[S|B]</b>, <b>DMALDP\<S|B></b>, <b>DMAST[S|B]</b>, and
158 * <b>DMASTP\<S|B></b> microcode instructions, the enumeration
159 * ALT_DMA_PROGRAM_INST_MOD_SINGLE specifies the <b>S</b> option modifier
160 * while the enumeration ALT_DMA_PROGRAM_INST_MOD_BURST specifies the <b>B</b>
161 * option modifier. The enumeration ALT_DMA_PROGRAM_INST_MOD_NONE specifies
162 * that no modifier is present for instructions where use of <b>[S|B]</b> is
163 * optional.
164 *
165 * For the <b>DMAWFP</b> microcode instruction, the enumerations
166 * ALT_DMA_PROGRAM_INST_MOD_SINGLE, ALT_DMA_PROGRAM_INST_MOD_BURST, or
167 * ALT_DMA_PROGRAM_INST_MOD_PERIPH each specify one of the corresponding
168 * options <b>\<single|burst|periph></b>.
169 */
170typedef enum ALT_DMA_PROGRAM_INST_MOD_e
171{
172    /*!
173     * This DMA instruction modifier specifies that no special modifier is
174     * added to the instruction.
175     */
176    ALT_DMA_PROGRAM_INST_MOD_NONE,
177
178    /*!
179     * Depending on the DMA microcode instruction modified, this modifier
180     * specifies <b>S</b> case for a <b>[S|B]</b> or a <b>\<single></b> for a
181     * <b>\<single|burst|periph></b>.
182     */
183    ALT_DMA_PROGRAM_INST_MOD_SINGLE,
184
185    /*!
186     * Depending on the DMA microcode instruction modified, this modifier
187     * specifies <b>B</b> case for a <b>[S|B]</b> or a <b>\<burst></b> for a
188     * <b>\<single|burst|periph></b>.
189     */
190    ALT_DMA_PROGRAM_INST_MOD_BURST,
191
192    /*!
193     * This DMA instruction modifier specifies a <b>\<periph></b> for a
194     * <b>\<single|burst|periph></b>.
195     */
196    ALT_DMA_PROGRAM_INST_MOD_PERIPH
197}
198ALT_DMA_PROGRAM_INST_MOD_t;
199
200/*!
201 * This function initializes a system memory buffer for use as a DMA microcode
202 * program buffer. This should be the first API call made on the program
203 * buffer type.
204 *
205 * \param       pgm
206 *              A pointer to a DMA program buffer structure.
207 *
208 * \retval      ALT_E_SUCCESS   The operation was successful.
209 * \retval      ALT_E_ERROR     Details about error status code
210 */
211ALT_STATUS_CODE alt_dma_program_init(ALT_DMA_PROGRAM_t * pgm);
212
213/*!
214 * This function verifies that the DMA microcode program buffer is no longer
215 * in use and performs any needed uninitialization steps.
216 *
217 * \param       pgm
218 *              A pointer to a DMA program buffer structure.
219 *
220 * \retval      ALT_E_SUCCESS   The operation was successful.
221 * \retval      ALT_E_ERROR     Details about error status code
222 */
223ALT_STATUS_CODE alt_dma_program_uninit(ALT_DMA_PROGRAM_t * pgm);
224
225/*!
226 * This function clears the existing DMA microcode program in the given
227 * program buffer.
228 *
229 * \param       pgm
230 *              A pointer to a DMA program buffer structure.
231 *
232 * \retval      ALT_E_SUCCESS   The operation was successful.
233 * \retval      ALT_E_ERROR     Details about error status code.
234 */
235ALT_STATUS_CODE alt_dma_program_clear(ALT_DMA_PROGRAM_t * pgm);
236
237/*!
238 * This function validate that the given DMA microcode program buffer contains
239 * a well formed program. If caches are enabled, the program buffer contents
240 * will be cleaned to RAM.
241 *
242 * \param       pgm
243 *              A pointer to a DMA program buffer structure.
244 *
245 * \retval      ALT_E_SUCCESS   The given program is well formed.
246 * \retval      ALT_E_ERROR     The given program is not well formed.
247 * \retval      ALT_E_TMO       The cache operation timed out.
248 */
249ALT_STATUS_CODE alt_dma_program_validate(const ALT_DMA_PROGRAM_t * pgm);
250
251/*!
252 * This function reports the number bytes incremented for the register
253 * specified. The purpose is to determine the progress of an ongoing DMA
254 * transfer.
255 *
256 * It is implemented by calculating the difference of the programmed SAR or DAR
257 * with the current channel SAR or DAR register value.
258 *
259 * \param       pgm
260 *              A pointer to a DMA program buffer structure.
261 *
262 * \param       channel
263 *              The channel that the program is running on.
264 *
265 * \param       reg
266 *              Register to change the value for. Valid for only
267 *              ALT_DMA_PROGRAM_REG_SAR and ALT_DMA_PROGRAM_REG_DAR.
268 *
269 * \param       current
270 *              The current snapshot value of the register read from the DMA
271 *              channel.
272 *
273 * \param       progress
274 *              [out] A pointer to a memory location that will be used to store
275 *              the number of bytes transfered.
276 *
277 * \retval      ALT_E_SUCCESS   The operation was successful.
278 * \retval      ALT_E_ERROR     Details about error status code.
279 * \retval      ALT_E_BAD_ARG   The specified channel is invalid, the specified
280 *                              register is invalid, or the DMAMOV for the
281 *                              specified register has not yet been assembled
282 *                              in the current program buffer.
283 */
284ALT_STATUS_CODE alt_dma_program_progress_reg(ALT_DMA_PROGRAM_t * pgm,
285                                             ALT_DMA_PROGRAM_REG_t reg,
286                                             uint32_t current, uint32_t * progress);
287
288/*!
289 * This function updates a pre-existing DMAMOV value affecting the SAR or DAR
290 * registers. This allows for pre-assembled programs that can be used on
291 * different source and destination addresses.
292 *
293 * \param       pgm
294 *              A pointer to a DMA program buffer structure.
295 *
296 * \param       reg
297 *              Register to change the value for. Valid for only
298 *              ALT_DMA_PROGRAM_REG_SAR and ALT_DMA_PROGRAM_REG_DAR.
299 *
300 * \param       val
301 *              The value to update to.
302 *
303 * \retval      ALT_E_SUCCESS   The operation was successful.
304 * \retval      ALT_E_ERROR     Details about error status code.
305 * \retval      ALT_E_BAD_ARG   The specified register is invalid or the DMAMOV
306 *                              for the specified register has not yet been
307 *                              assembled in the current program buffer.
308 */
309ALT_STATUS_CODE alt_dma_program_update_reg(ALT_DMA_PROGRAM_t * pgm,
310                                           ALT_DMA_PROGRAM_REG_t reg, uint32_t val);
311
312/*!
313 */
314
315/*!
316 * Assembles a DMAADDH (Add Halfword) instruction into the microcode program
317 * buffer. This instruction uses 3 bytes of buffer space.
318 *
319 * \param       pgm
320 *              The DMA program buffer to contain the assembled instruction.
321 *
322 * \param       addr_reg
323 *              The channel address register (ALT_DMA_PROGRAM_REG_DAR or
324 *              ALT_DMA_PROGRAM_REG_SAR) to add the value to.
325 *
326 * \param       val
327 *              The 16-bit unsigned value to add to the channel address
328 *              register.
329 *
330 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
331 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
332 * \retval      ALT_E_BAD_ARG       Invalid channel register specified.
333 */
334// Assembler Syntax: DMAADDH <address_register>, <16-bit immediate>
335ALT_STATUS_CODE alt_dma_program_DMAADDH(ALT_DMA_PROGRAM_t * pgm,
336                                        ALT_DMA_PROGRAM_REG_t addr_reg, uint16_t val);
337
338/*!
339 * Assembles a DMAADNH (Add Negative Halfword) instruction into the microcode
340 * program buffer. This instruction uses 3 bytes of buffer space.
341 *
342 * \param       pgm
343 *              The DMA programm buffer to contain the assembled instruction.
344 *
345 * \param       addr_reg
346 *              The channel address register (ALT_DMA_PROGRAM_REG_DAR or
347 *              ALT_DMA_PROGRAM_REG_SAR) to add the value to.
348 *
349 * \param       val
350 *              The 16-bit unsigned value to add to the channel address
351 *              register.
352 *
353 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
354 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
355 * \retval      ALT_E_BAD_ARG       Invalid channel register specified.
356 */
357// Assembler Syntax: DMAADNH <address_register>, <16-bit immediate>
358ALT_STATUS_CODE alt_dma_program_DMAADNH(ALT_DMA_PROGRAM_t * pgm,
359                                        ALT_DMA_PROGRAM_REG_t addr_reg, uint16_t val);
360
361/*!
362 * Assembles a DMAEND (End) instruction into the microcode program buffer.
363 * This instruction uses 1 byte of buffer space.
364 *
365 * \param       pgm
366 *              The DMA programm buffer to contain the assembled instruction.
367 *
368 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
369 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
370 */
371// Assembler Syntax: DMAEND
372ALT_STATUS_CODE alt_dma_program_DMAEND(ALT_DMA_PROGRAM_t * pgm);
373
374/*!
375 * Assembles a DMAFLUSHP (Flush Peripheral) instruction into the microcode
376 * program buffer. This instruction uses 2 bytes of buffer space.
377 *
378 * \param       pgm
379 *              The DMA programm buffer to contain the assembled instruction.
380 *
381 * \param       periph
382 *              The peripheral to flush.
383 *
384 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
385 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
386 * \retval      ALT_E_BAD_ARG       Invalid peripheral specified.
387 */
388// Assembler Syntax: DMAFLUSHP <peripheral>
389ALT_STATUS_CODE alt_dma_program_DMAFLUSHP(ALT_DMA_PROGRAM_t * pgm,
390                                          ALT_DMA_PERIPH_t periph);
391
392/*!
393 * Assembles a DMAGO (Go) instruction into the microcode program buffer. This
394 * instruction uses 6 bytes of buffer space.
395 *
396 * \param       pgm
397 *              The DMA programm buffer to contain the assembled instruction.
398 *
399 * \param       channel
400 *              The stopped channel to act upon.
401 *
402 * \param       val
403 *              The value to write to the channel program counter register.
404 *
405 * \param       sec
406 *              The security state for the operation.
407 *
408 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
409 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
410 * \retval      ALT_E_BAD_ARG       Invalid channel or security specified.
411 */
412// Assembler Syntax: DMAGO <channel_number>, <32-bit_immediate> [, ns]
413ALT_STATUS_CODE alt_dma_program_DMAGO(ALT_DMA_PROGRAM_t * pgm,
414                                      ALT_DMA_CHANNEL_t channel, uint32_t val,
415                                      ALT_DMA_SECURITY_t sec);
416
417/*!
418 * Assembles a DMAKILL (Kill) instruction into the microcode program buffer.
419 * This instruction uses 1 byte of buffer space.
420 *
421 * \param       pgm
422 *              The DMA programm buffer to contain the assembled instruction.
423 *
424 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
425 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
426 */
427// Assembler Syntax: DMAKILL
428ALT_STATUS_CODE alt_dma_program_DMAKILL(ALT_DMA_PROGRAM_t * pgm);
429
430/*!
431 * Assembles a DMALD (Load) instruction into the microcode program buffer.
432 * This instruction uses 1 byte of buffer space.
433 *
434 * \param       pgm
435 *              The DMA programm buffer to contain the assembled instruction.
436 *
437 * \param       mod
438 *              The program instruction modifier for the type of transfer.
439 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and
440 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
441 *
442 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
443 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
444 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier specified.
445 */
446// Assembler Syntax: DMALD[S|B]
447ALT_STATUS_CODE alt_dma_program_DMALD(ALT_DMA_PROGRAM_t * pgm,
448                                      ALT_DMA_PROGRAM_INST_MOD_t mod);
449
450/*!
451 * Assembles a DMALDP (Load and notify Peripheral) instruction into the
452 * microcode program buffer. This instruction uses 2 bytes of buffer space.
453 *
454 * \param       pgm
455 *              The DMA programm buffer to contain the assembled instruction.
456 *
457 * \param       mod
458 *              The program instruction modifier for the type of transfer.
459 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and
460 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
461 *
462 * \param       periph
463 *              The peripheral to notify.
464 *
465 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
466 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
467 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier or peripheral
468 *                                  specified.
469 */
470// Assembler Syntax: DMALDP<S|B> <peripheral>
471ALT_STATUS_CODE alt_dma_program_DMALDP(ALT_DMA_PROGRAM_t * pgm,
472                                       ALT_DMA_PROGRAM_INST_MOD_t mod, ALT_DMA_PERIPH_t periph);
473
474/*!
475 * Assembles a DMALP (Loop) instruction into the microcode program buffer.
476 * This instruction uses 2 bytes of buffer space.
477 *
478 * \param       pgm
479 *              The DMA programm buffer to contain the assembled instruction.
480 *
481 * \param       iterations
482 *              The number of iterations to run for. Valid values are 1 - 256.
483 *
484 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
485 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
486 * \retval      ALT_E_BAD_ARG       Invalid iterations specified.
487 * \retval      ALT_E_BAD_OPERATION All loop registers are in use.
488 */
489// Assembler Syntax: DMALP [<LC0>|<LC1>] <loop_iterations>
490ALT_STATUS_CODE alt_dma_program_DMALP(ALT_DMA_PROGRAM_t * pgm,
491                                      uint32_t iterations);
492
493/*!
494 * Assembles a DMALPEND (Loop End) instruction into the microcode program
495 * buffer. This instruction uses 2 bytes of buffer space.
496 *
497 * \param       pgm
498 *              The DMA programm buffer to contain the assembled instruction.
499 *
500 * \param       mod
501 *              The program instruction modifier for the loop terminator. Only
502 *              ALT_DMA_PROGRAM_INST_MOD_NONE, ALT_DMA_PROGRAM_INST_MOD_SINGLE
503 *              and ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
504 *
505 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
506 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
507 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier specified.
508 * \retval      ALT_E_ARG_RANGE     Loop size is too large to be supported.
509 * \retval      ALT_E_BAD_OPERATION A valid DMALP or DMALPFE was not added to
510 *                                  the program buffer before adding this
511 *                                  DMALPEND instruction.
512 */
513// Assembler Syntax: DMALPEND[S|B]
514ALT_STATUS_CODE alt_dma_program_DMALPEND(ALT_DMA_PROGRAM_t * pgm,
515                                         ALT_DMA_PROGRAM_INST_MOD_t mod);
516
517/*!
518 * Assembles a DMALPFE (Loop Forever) instruction into the microcode program
519 * buffer. No instruction is added to the buffer but a previous DMALPEND to
520 * create an infinite loop.
521 *
522 * \param       pgm
523 *              The DMA programm buffer to contain the assembled instruction.
524 *
525 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
526 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
527 */
528// Assembler Syntax: DMALPFE
529ALT_STATUS_CODE alt_dma_program_DMALPFE(ALT_DMA_PROGRAM_t * pgm);
530
531/*!
532 * Assembles a DMAMOV (Move) instruction into the microcode program buffer.
533 * This instruction uses 6 bytes of buffer space.
534 *
535 * \param       pgm
536 *              The DMA programm buffer to contain the assembled instruction.
537 *
538 * \param       chan_reg
539 *              The channel non-looping register (ALT_DMA_PROGRAM_REG_SAR,
540 *              ALT_DMA_PROGRAM_REG_DAR or ALT_DMA_PROGRAM_REG_CCR) to copy
541 *              the value to.
542 *
543 * \param       val
544 *              The value to write to the specified register.
545 *
546 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
547 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
548 * \retval      ALT_E_BAD_ARG       Invalid channel register specified.
549 */
550// Assembler Syntax: DMAMOV <destination_register>, <32-bit_immediate>
551ALT_STATUS_CODE alt_dma_program_DMAMOV(ALT_DMA_PROGRAM_t * pgm,
552                                       ALT_DMA_PROGRAM_REG_t chan_reg, uint32_t val);
553
554/*!
555 * Assembles a DMANOP (No Operation) instruction into the microcode program
556 * buffer. This instruction uses 1 byte of buffer space.
557 *
558 * \param       pgm
559 *              The DMA programm buffer to contain the assembled instruction.
560 *
561 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
562 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
563 */
564// Assembler Syntax: DMANOP
565ALT_STATUS_CODE alt_dma_program_DMANOP(ALT_DMA_PROGRAM_t * pgm);
566
567/*!
568 * Assembles a DMARMB (Read Memory Barrier) instruction into the microcode
569 * program buffer. This instruction uses 1 byte of buffer space.
570 *
571 * \param       pgm
572 *              The DMA programm buffer to contain the assembled instruction.
573 *
574 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
575 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
576 */
577// Assembler Syntax: DMARMB
578ALT_STATUS_CODE alt_dma_program_DMARMB(ALT_DMA_PROGRAM_t * pgm);
579
580/*!
581 * Assembles a DMASEV (Send Event) instruction into the microcode program
582 * buffer. This instruction uses 2 byte of buffer space.
583 *
584 * \param       pgm
585 *              The DMA programm buffer to contain the assembled instruction.
586 *
587 * \param       evt
588 *              The event to send.
589 *
590 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
591 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
592 * \retval      ALT_E_BAD_ARG       Invalid event specified.
593 */
594// Assembler Syntax: DMASEV <event_num>
595ALT_STATUS_CODE alt_dma_program_DMASEV(ALT_DMA_PROGRAM_t * pgm,
596                                       ALT_DMA_EVENT_t evt);
597
598/*!
599 * Assembles a DMAST (Store) instruction into the microcode program buffer.
600 * This instruction uses 1 byte of buffer space.
601 *
602 * \param       pgm
603 *              The DMA programm buffer to contain the assembled instruction.
604 *
605 * \param       mod
606 *              The program instruction modifier for the type of transfer.
607 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and
608 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
609 *
610 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
611 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
612 */
613// Assembler Syntax: DMAST[S|B]
614ALT_STATUS_CODE alt_dma_program_DMAST(ALT_DMA_PROGRAM_t * pgm,
615                                      ALT_DMA_PROGRAM_INST_MOD_t mod);
616
617/*!
618 * Assembles a DMASTP (Store and notify Peripheral) instruction into the
619 * microcode program buffer. This instruction uses 2 bytes of buffer space.
620 *
621 * \param       pgm
622 *              The DMA programm buffer to contain the assembled instruction.
623 *
624 * \param       mod
625 *              The program instruction modifier for the type of transfer.
626 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and
627 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
628 *
629 * \param       periph
630 *              The peripheral to notify.
631 *
632 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
633 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
634 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier or peripheral
635 *                                  specified.
636 */
637// Assembler Syntax: DMASTP<S|B> <peripheral>
638ALT_STATUS_CODE alt_dma_program_DMASTP(ALT_DMA_PROGRAM_t * pgm,
639                                       ALT_DMA_PROGRAM_INST_MOD_t mod, ALT_DMA_PERIPH_t periph);
640
641/*!
642 * Assembles a DMASTZ (Store Zero) instruction into the microcode program
643 * buffer. This instruction uses 1 byte of buffer space.
644 *
645 * \param       pgm
646 *              The DMA programm buffer to contain the assembled instruction.
647 *
648 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
649 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
650 */
651// Assembler Syntax: DMASTZ
652ALT_STATUS_CODE alt_dma_program_DMASTZ(ALT_DMA_PROGRAM_t * pgm);
653
654/*!
655 * Assembles a DMAWFE (Wait For Event) instruction into the microcode program
656 * buffer. This instruction uses 2 byte of buffer space.
657 *
658 * \param       pgm
659 *              The DMA programm buffer to contain the assembled instruction.
660 *
661 * \param       evt
662 *              The event to wait for.
663 *
664 * \param       invalid
665 *              If invalid is set to true, the instruction will be configured
666 *              to invalidate the instruction cache for the current DMA
667 *              thread.
668 *
669 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
670 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
671 * \retval      ALT_E_BAD_ARG       Invalid event specified.
672 */
673// Assembler Syntax: DMAWFE <event_num>[, invalid]
674ALT_STATUS_CODE alt_dma_program_DMAWFE(ALT_DMA_PROGRAM_t * pgm,
675                                       ALT_DMA_EVENT_t evt, bool invalid);
676
677/*!
678 * Assembles a DMAWFP (Wait for Peripheral) instruction into the microcode
679 * program buffer. This instruction uses 2 bytes of buffer space.
680 *
681 * \param       pgm
682 *              The DMA programm buffer to contain the assembled instruction.
683 *
684 * \param       periph
685 *              The peripheral to wait on.
686 *
687 * \param       mod
688 *              The program instruction modifier for the type of transfer.
689 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE,
690 *              ALT_DMA_PROGRAM_INST_MOD_BURST, or
691 *              ALT_DMA_PROGRAM_INST_MOD_PERIPH are valid options.
692 *
693 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
694 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
695 * \retval      ALT_E_BAD_ARG       Invalid peripheral or instruction modifier
696 *                                  specified.
697 */
698// Assembler Syntax: DMAWFP <peripheral>, <single|burst|periph>
699ALT_STATUS_CODE alt_dma_program_DMAWFP(ALT_DMA_PROGRAM_t * pgm,
700                                       ALT_DMA_PERIPH_t periph, ALT_DMA_PROGRAM_INST_MOD_t mod);
701
702/*!
703 * Assembles a DMAWMB (Write Memory Barrier) instruction into the microcode
704 * program buffer. This instruction uses 1 byte of buffer space.
705 *
706 * \param       pgm
707 *              The DMA programm buffer to contain the assembled instruction.
708 *
709 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
710 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
711 */
712// Assembler Syntax: DMAWMB
713ALT_STATUS_CODE alt_dma_program_DMAWMB(ALT_DMA_PROGRAM_t * pgm);
714
715/*!
716 * \addtogroup DMA_CCR Support for DMAMOV CCR
717 *
718 * The ALT_DMA_CCR_OPT_* macro definitions are defined here to facilitate the
719 * dynamic microcode programming of the assembler directive:
720\verbatim
721
722DMAMOV CCR, [SB<1-16>] [SS<8|16|32|64|128>] [SA<I|F>]
723            [SP<imm3>] [SC<imm4>]
724            [DB<1-16>] [DS<8|16|32|64|128>] [DA<I|F>]
725            [DP<imm3>] [DC<imm4>]
726            [ES<8|16|32|64|128>]
727
728\endverbatim
729* with a DMAMOV instruction (see: alt_dma_program_DMAMOV()).
730*
731* For example the assembler directive:
732\verbatim
733DMAMOV CCR SB1 SS32 DB1 DS32
734\endverbatim
735* would be dynamically programmed with the following API call:
736\verbatim
737alt_dma_program_DMAMOV( pgm,
738                        ALT_DMA_PROGRAM_REG_CCR,
739                        (   ALT_DMA_CCR_OPT_SB1
740                          | ALT_DMA_CCR_OPT_SS32
741                          | ALT_DMA_CCR_OPT_SA_DEFAULT
742                          | ALT_DMA_CCR_OPT_SP_DEFAULT
743                          | ALT_DMA_CCR_OPT_SC_DEFAULT
744                          | ALT_DMA_CCR_OPT_DB1
745                          | ALT_DMA_CCR_OPT_DS32
746                          | ALT_DMA_CCR_OPT_DA_DEFAULT
747                          | ALT_DMA_CCR_OPT_DP_DEFAULT
748                          | ALT_DMA_CCR_OPT_DC_DEFAULT
749                          | ALT_DMA_CCR_OPT_ES8
750                        )
751                      );
752\endverbatim
753*
754* Each CCR option category should be specified regardless of whether it
755* specifies a custom value or the normal default value (i.e. an
756* ALT_DMA_CCR_OPT_*_DEFAULT.
757*
758* @{
759*/
760
761/*
762 * Source Address {Fixed,Incrementing}
763 */
764/*! Source Address Fixed address burst. */
765#define ALT_DMA_CCR_OPT_SAF         (0 << 0)
766/*! Source Address Incrementing address burst. */
767#define ALT_DMA_CCR_OPT_SAI         (1 << 0)
768/*! Source Address Default value. */
769#define ALT_DMA_CCR_OPT_SA_DEFAULT  ALT_DMA_CCR_OPT_SAI
770
771/*
772 * Source burst Size (in bits)
773 */
774/*! Source burst Size of 8 bits. */
775#define ALT_DMA_CCR_OPT_SS8         (0 << 1)
776/*! Source burst Size of 16 bits. */
777#define ALT_DMA_CCR_OPT_SS16        (1 << 1)
778/*! Source burst Size of 32 bits. */
779#define ALT_DMA_CCR_OPT_SS32        (2 << 1)
780/*! Source burst Size of 64 bits. */
781#define ALT_DMA_CCR_OPT_SS64        (3 << 1)
782/*! Source burst Size of 128 bits. */
783#define ALT_DMA_CCR_OPT_SS128       (4 << 1)
784/*! Source burst Size default bits. */
785#define ALT_DMA_CCR_OPT_SS_DEFAULT  ALT_DMA_CCR_OPT_SS8
786
787/*
788 * Source burst Length (in transfer(s))
789 */
790/*! Source Burst length of 1 transfer. */
791#define ALT_DMA_CCR_OPT_SB1         (0x0 << 4)
792/*! Source Burst length of 2 transfers. */
793#define ALT_DMA_CCR_OPT_SB2         (0x1 << 4)
794/*! Source Burst length of 3 transfers. */
795#define ALT_DMA_CCR_OPT_SB3         (0x2 << 4)
796/*! Source Burst length of 4 transfers. */
797#define ALT_DMA_CCR_OPT_SB4         (0x3 << 4)
798/*! Source Burst length of 5 transfers. */
799#define ALT_DMA_CCR_OPT_SB5         (0x4 << 4)
800/*! Source Burst length of 6 transfers. */
801#define ALT_DMA_CCR_OPT_SB6         (0x5 << 4)
802/*! Source Burst length of 7 transfers. */
803#define ALT_DMA_CCR_OPT_SB7         (0x6 << 4)
804/*! Source Burst length of 8 transfers. */
805#define ALT_DMA_CCR_OPT_SB8         (0x7 << 4)
806/*! Source Burst length of 9 transfers. */
807#define ALT_DMA_CCR_OPT_SB9         (0x8 << 4)
808/*! Source Burst length of 10 transfers. */
809#define ALT_DMA_CCR_OPT_SB10        (0x9 << 4)
810/*! Source Burst length of 11 transfers. */
811#define ALT_DMA_CCR_OPT_SB11        (0xa << 4)
812/*! Source Burst length of 12 transfers. */
813#define ALT_DMA_CCR_OPT_SB12        (0xb << 4)
814/*! Source Burst length of 13 transfers. */
815#define ALT_DMA_CCR_OPT_SB13        (0xc << 4)
816/*! Source Burst length of 14 transfers. */
817#define ALT_DMA_CCR_OPT_SB14        (0xd << 4)
818/*! Source Burst length of 15 transfers. */
819#define ALT_DMA_CCR_OPT_SB15        (0xe << 4)
820/*! Source Burst length of 16 transfers. */
821#define ALT_DMA_CCR_OPT_SB16        (0xf << 4)
822/*! Source Burst length default transfers. */
823#define ALT_DMA_CCR_OPT_SB_DEFAULT  ALT_DMA_CCR_OPT_SB1
824
825/*
826 * Source Protection
827 */
828/*! Source Protection bits for AXI bus ARPROT[2:0]. */
829#define ALT_DMA_CCR_OPT_SP(imm3)    ((imm3) << 8)
830/*! Source Protection bits default value. */
831#define ALT_DMA_CCR_OPT_SP_DEFAULT  ALT_DMA_CCR_OPT_SP(0)
832
833/*
834 * Source cache
835 */
836/*! Source Cache bits for AXI bus ARCACHE[2:0]. */
837#define ALT_DMA_CCR_OPT_SC(imm4)    ((imm4) << 11)
838/*! Source Cache bits default value. */
839#define ALT_DMA_CCR_OPT_SC_DEFAULT  ALT_DMA_CCR_OPT_SC(0)
840
841/*
842 * Destination Address {Fixed,Incrementing}
843 */
844/*! Destination Address Fixed address burst. */
845#define ALT_DMA_CCR_OPT_DAF         (0 << 14)
846/*! Destination Address Incrementing address burst. */
847#define ALT_DMA_CCR_OPT_DAI         (1 << 14)
848/*! Destination Address Default value. */
849#define ALT_DMA_CCR_OPT_DA_DEFAULT  ALT_DMA_CCR_OPT_DAI
850
851/*
852 * Destination burst Size (in bits)
853 */
854/*! Destination burst Size of 8 bits. */
855#define ALT_DMA_CCR_OPT_DS8         (0 << 15)
856/*! Destination burst Size of 16 bits. */
857#define ALT_DMA_CCR_OPT_DS16        (1 << 15)
858/*! Destination burst Size of 32 bits. */
859#define ALT_DMA_CCR_OPT_DS32        (2 << 15)
860/*! Destination burst Size of 64 bits. */
861#define ALT_DMA_CCR_OPT_DS64        (3 << 15)
862/*! Destination burst Size of 128 bits. */
863#define ALT_DMA_CCR_OPT_DS128       (4 << 15)
864/*! Destination burst Size default bits. */
865#define ALT_DMA_CCR_OPT_DS_DEFAULT  ALT_DMA_CCR_OPT_DS8
866
867/*
868 * Destination Burst length (in transfer(s))
869 */
870/*! Destination Burst length of 1 transfer. */
871#define ALT_DMA_CCR_OPT_DB1         (0x0 << 18)
872/*! Destination Burst length of 2 transfers. */
873#define ALT_DMA_CCR_OPT_DB2         (0x1 << 18)
874/*! Destination Burst length of 3 transfers. */
875#define ALT_DMA_CCR_OPT_DB3         (0x2 << 18)
876/*! Destination Burst length of 4 transfers. */
877#define ALT_DMA_CCR_OPT_DB4         (0x3 << 18)
878/*! Destination Burst length of 5 transfers. */
879#define ALT_DMA_CCR_OPT_DB5         (0x4 << 18)
880/*! Destination Burst length of 6 transfers. */
881#define ALT_DMA_CCR_OPT_DB6         (0x5 << 18)
882/*! Destination Burst length of 7 transfers. */
883#define ALT_DMA_CCR_OPT_DB7         (0x6 << 18)
884/*! Destination Burst length of 8 transfers. */
885#define ALT_DMA_CCR_OPT_DB8         (0x7 << 18)
886/*! Destination Burst length of 9 transfers. */
887#define ALT_DMA_CCR_OPT_DB9         (0x8 << 18)
888/*! Destination Burst length of 10 transfers. */
889#define ALT_DMA_CCR_OPT_DB10        (0x9 << 18)
890/*! Destination Burst length of 11 transfers. */
891#define ALT_DMA_CCR_OPT_DB11        (0xa << 18)
892/*! Destination Burst length of 12 transfers. */
893#define ALT_DMA_CCR_OPT_DB12        (0xb << 18)
894/*! Destination Burst length of 13 transfers. */
895#define ALT_DMA_CCR_OPT_DB13        (0xc << 18)
896/*! Destination Burst length of 14 transfers. */
897#define ALT_DMA_CCR_OPT_DB14        (0xd << 18)
898/*! Destination Burst length of 15 transfers. */
899#define ALT_DMA_CCR_OPT_DB15        (0xe << 18)
900/*! Destination Burst length of 16 transfers. */
901#define ALT_DMA_CCR_OPT_DB16        (0xf << 18)
902/*! Destination Burst length default transfers. */
903#define ALT_DMA_CCR_OPT_DB_DEFAULT  ALT_DMA_CCR_OPT_DB1
904
905/*
906 * Destination Protection
907 */
908/*! Destination Protection bits for AXI bus AWPROT[2:0]. */
909#define ALT_DMA_CCR_OPT_DP(imm3)    ((imm3) << 22)
910/*! Destination Protection bits default value. */
911#define ALT_DMA_CCR_OPT_DP_DEFAULT  ALT_DMA_CCR_OPT_DP(0)
912
913/*
914 * Destination Cache
915 */
916/*! Destination Cache bits for AXI bus AWCACHE[3,1:0]. */
917#define ALT_DMA_CCR_OPT_DC(imm4)    ((imm4) << 25)
918/*! Destination Cache bits default value. */
919#define ALT_DMA_CCR_OPT_DC_DEFAULT  ALT_DMA_CCR_OPT_DC(0)
920
921/*
922 * Endian Swap size (in bits)
923 */
924/*! Endian Swap: No swap, 8-bit data. */
925#define ALT_DMA_CCR_OPT_ES8         (0 << 28)
926/*! Endian Swap: Swap bytes within 16-bit data. */
927#define ALT_DMA_CCR_OPT_ES16        (1 << 28)
928/*! Endian Swap: Swap bytes within 32-bit data. */
929#define ALT_DMA_CCR_OPT_ES32        (2 << 28)
930/*! Endian Swap: Swap bytes within 64-bit data. */
931#define ALT_DMA_CCR_OPT_ES64        (3 << 28)
932/*! Endian Swap: Swap bytes within 128-bit data. */
933#define ALT_DMA_CCR_OPT_ES128       (4 << 28)
934/*! Endian Swap: Default byte swap. */
935#define ALT_DMA_CCR_OPT_ES_DEFAULT  ALT_DMA_CCR_OPT_ES8
936
937/*! Default CCR register options for a DMAMOV CCR assembler directive. */
938#define ALT_DMA_CCR_OPT_DEFAULT \
939    (ALT_DMA_CCR_OPT_SB1 | ALT_DMA_CCR_OPT_SS8 | ALT_DMA_CCR_OPT_SAI | \
940     ALT_DMA_CCR_OPT_SP(0) | ALT_DMA_CCR_OPT_SC(0) | \
941     ALT_DMA_CCR_OPT_DB1 | ALT_DMA_CCR_OPT_DS8 | ALT_DMA_CCR_OPT_DAI | \
942     ALT_DMA_CCR_OPT_DP(0) | ALT_DMA_CCR_OPT_DC(0) | \
943     ALT_DMA_CCR_OPT_ES8)
944
945/*!
946 * @}
947 */
948
949/*!
950 * @}
951 */
952
953#ifdef __cplusplus
954}
955#endif  /* __cplusplus */
956
957#endif /* __ALT_DMA_PROGRAM_H__ */
Note: See TracBrowser for help on using the repository browser.