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 */