source: rtems/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_dma_program.h @ 76386c1

4.115
Last change on this file since 76386c1 was 76386c1, checked in by Sebastian Huber <sebastian.huber@…>, on 08/26/14 at 14:00:44

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