dma: Introduce dma_get_cfg() interface
[platform/kernel/u-boot.git] / include / dma-uclass.h
1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * Copyright (C) 2018 Álvaro Fernández Rojas <noltari@gmail.com>
4  * Copyright (C) 2015 - 2018 Texas Instruments Incorporated <www.ti.com>
5  * Written by Mugunthan V N <mugunthanvnm@ti.com>
6  *
7  */
8
9 #ifndef _DMA_UCLASS_H
10 #define _DMA_UCLASS_H
11
12 /* See dma.h for background documentation. */
13
14 #include <dma.h>
15
16 struct ofnode_phandle_args;
17
18 /*
19  * struct dma_ops - Driver model DMA operations
20  *
21  * The uclass interface is implemented by all DMA devices which use
22  * driver model.
23  */
24 struct dma_ops {
25 #ifdef CONFIG_DMA_CHANNELS
26         /**
27          * of_xlate - Translate a client's device-tree (OF) DMA specifier.
28          *
29          * The DMA core calls this function as the first step in implementing
30          * a client's dma_get_by_*() call.
31          *
32          * If this function pointer is set to NULL, the DMA core will use a
33          * default implementation, which assumes #dma-cells = <1>, and that
34          * the DT cell contains a simple integer DMA Channel.
35          *
36          * At present, the DMA API solely supports device-tree. If this
37          * changes, other xxx_xlate() functions may be added to support those
38          * other mechanisms.
39          *
40          * @dma: The dma struct to hold the translation result.
41          * @args:       The dma specifier values from device tree.
42          * @return 0 if OK, or a negative error code.
43          */
44         int (*of_xlate)(struct dma *dma,
45                         struct ofnode_phandle_args *args);
46         /**
47          * request - Request a translated DMA.
48          *
49          * The DMA core calls this function as the second step in
50          * implementing a client's dma_get_by_*() call, following a successful
51          * xxx_xlate() call, or as the only step in implementing a client's
52          * dma_request() call.
53          *
54          * @dma: The DMA struct to request; this has been filled in by
55          *   a previoux xxx_xlate() function call, or by the caller of
56          *   dma_request().
57          * @return 0 if OK, or a negative error code.
58          */
59         int (*request)(struct dma *dma);
60         /**
61          * free - Free a previously requested dma.
62          *
63          * This is the implementation of the client dma_free() API.
64          *
65          * @dma: The DMA to free.
66          * @return 0 if OK, or a negative error code.
67          */
68         int (*free)(struct dma *dma);
69         /**
70          * enable() - Enable a DMA Channel.
71          *
72          * @dma: The DMA Channel to manipulate.
73          * @return zero on success, or -ve error code.
74          */
75         int (*enable)(struct dma *dma);
76         /**
77          * disable() - Disable a DMA Channel.
78          *
79          * @dma: The DMA Channel to manipulate.
80          * @return zero on success, or -ve error code.
81          */
82         int (*disable)(struct dma *dma);
83         /**
84          * prepare_rcv_buf() - Prepare/Add receive DMA buffer.
85          *
86          * @dma: The DMA Channel to manipulate.
87          * @dst: The receive buffer pointer.
88          * @size: The receive buffer size
89          * @return zero on success, or -ve error code.
90          */
91         int (*prepare_rcv_buf)(struct dma *dma, void *dst, size_t size);
92         /**
93          * receive() - Receive a DMA transfer.
94          *
95          * @dma: The DMA Channel to manipulate.
96          * @dst: The destination pointer.
97          * @metadata: DMA driver's specific data
98          * @return zero on success, or -ve error code.
99          */
100         int (*receive)(struct dma *dma, void **dst, void *metadata);
101         /**
102          * send() - Send a DMA transfer.
103          *
104          * @dma: The DMA Channel to manipulate.
105          * @src: The source pointer.
106          * @len: Length of the data to be sent (number of bytes).
107          * @metadata: DMA driver's specific data
108          * @return zero on success, or -ve error code.
109          */
110         int (*send)(struct dma *dma, void *src, size_t len, void *metadata);
111         /**
112          * get_cfg() - Get DMA channel configuration for client's use
113          *
114          * @dma:    The DMA Channel to manipulate
115          * @cfg_id: DMA provider specific ID to identify what
116          *          configuration data client needs
117          * @data:   Pointer to store pointer to DMA driver specific
118          *          configuration data for the given cfg_id (output param)
119          * @return zero on success, or -ve error code.
120          */
121         int (*get_cfg)(struct dma *dma, u32 cfg_id, void **data);
122 #endif /* CONFIG_DMA_CHANNELS */
123         /**
124          * transfer() - Issue a DMA transfer. The implementation must
125          *   wait until the transfer is done.
126          *
127          * @dev: The DMA device
128          * @direction: direction of data transfer (should be one from
129          *   enum dma_direction)
130          * @dst: The destination pointer.
131          * @src: The source pointer.
132          * @len: Length of the data to be copied (number of bytes).
133          * @return zero on success, or -ve error code.
134          */
135         int (*transfer)(struct udevice *dev, int direction, void *dst,
136                         void *src, size_t len);
137 };
138
139 #endif /* _DMA_UCLASS_H */