xref: /openbmc/u-boot/include/dma-uclass.h (revision d94604d5)
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 #endif /* CONFIG_DMA_CHANNELS */
112 	/**
113 	 * transfer() - Issue a DMA transfer. The implementation must
114 	 *   wait until the transfer is done.
115 	 *
116 	 * @dev: The DMA device
117 	 * @direction: direction of data transfer (should be one from
118 	 *   enum dma_direction)
119 	 * @dst: The destination pointer.
120 	 * @src: The source pointer.
121 	 * @len: Length of the data to be copied (number of bytes).
122 	 * @return zero on success, or -ve error code.
123 	 */
124 	int (*transfer)(struct udevice *dev, int direction, void *dst,
125 			void *src, size_t len);
126 };
127 
128 #endif /* _DMA_UCLASS_H */
129