1/*
2 * Copyright 2017, Data61
3 * Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4 * ABN 41 687 119 230.
5 *
6 * This software may be distributed and modified according to the terms of
7 * the BSD 2-Clause license. Note that NO WARRANTY is provided.
8 * See "LICENSE_BSD2.txt" for details.
9 *
10 * @TAG(DATA61_BSD)
11 */
12
13#pragma once
14
15#include <platsupport/io.h>
16#include <stdint.h>
17
18#include <platsupport/plat/dma330.h>
19
20/* ARM PL-330 (DMA-330) DMA controller */
21
22struct dma330_dev;
23typedef struct dma330_dev* dma330_t;
24
25/**
26 * Callback for signal handling
27 * @param[in] dma330  A handle to the DMA330 controller that was monitoring the event
28 * @param[in] signal  The signal, in the address space of the channel, that cause the IRQ
29 * @param[in] pc      The instruction pointer of the thread that caused the signal
30 * @param[in] status  The status of the thread that caused the signal as presented in the csr register.
31 * @param[in] token   The token that the caller registered with this callback.
32 * @return            The application should return 0 if the transfer should be halted.
33 */
34typedef int (*dma330_signal_cb)(dma330_t* dma330, int signal, uintptr_t pc, uint32_t status, void* token);
35
36/**
37 * Initialise the DMA controller
38 * @praam[in]  id      The DMA device ID to be initialised
39 * @param[in]  ops     io operations for the initialisation process
40 * @param[out] dma330  on success, contains a handle to the initialised device
41 * @return             0 on success
42 */
43int dma330_init(enum dma330_id id, struct ps_io_ops* ops, dma330_t* dma330);
44
45/**
46 * Initialise the DMA controller with a provided base address
47 * @praam[in]  id          The DMA device ID to be initialised
48 * @param[in]  dma330_base The base address of the device for IO access.
49 * @param[in]  clk_sys     A handle to the clock subsytem for initialisation
50 * @param[out] dma330      on success, contains a handle to the initialised device
51 * @return                 0 on success
52 */
53int dma330_init_base(enum dma330_id id, void* dma330_base, clock_sys_t* clk_sys,
54                     dma330_t* dma330);
55
56/**
57 * Initiates a DMA transfer
58 * @param[in] dma330  a handle to the dma device
59 * @param[in] channel The channel to use for the transfer
60 * @param[in] program The physical address of the DMA330 micro-code to execute.
61 * @param[in] cb      A callback to call when the channel thread produces an event.
62 * @param[in] token   A token to pass, unmodified, to the callback.
63 * @return            0 on success
64 */
65int dma330_xfer(dma330_t* dma330, int channel, uintptr_t program, dma330_signal_cb cb, void* token);
66
67/**
68 * Allows the dma engine to handle an IRQ
69 * @param[in] dma330 a handle to the dma device
70 * @return           0 if an IRQ was indeed pending
71 */
72int dma330_handle_irq(dma330_t* dma330);
73
74/***********************
75 *** Program presets ***
76 ***********************/
77
78/**
79 * Compiles a dma330 program.
80 * 32 bytes will be reserved at the beginning of the program for argument passing
81 * @param[in]  source_code  DMA330 assembly program
82 * @param[out] bin          The resulting binary program
83 * @return                  0 on success, or line number on failure
84 */
85int dma330_compile(char* source_code, void* bin);
86
87/**
88 * Loads a preset micro code for a copy program
89 * The copy program sends signal #0 + channel when complete
90 * @param[in]  channel      The channel which the program will be executed on
91 * @param[out] bin          An address to store the compiled dma330 program to
92 */
93void dma330_copy_compile(int channel, void* bin);
94
95/**
96 * Configures a copy program.
97 * The source and destination must be hard coded into the micro code. This
98 * function takes an existing binary and adjusts the relevant parameters.
99 * @param[in]    psrc  The physical source address of the copy operation
100 * @param[in]    pdst  The physical destination address of the copy operation
101 * @param[in]    len   The number of bytes to copy
102 * @param[inout] vbin  The virtual address of a compiled copy program binary
103 */
104int dma330_copy_configure(uintptr_t psrc, uintptr_t pdst, size_t len, void* vbin);
105
106