~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/driver-api/dmaengine/client.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/driver-api/dmaengine/client.rst (Version linux-6.12-rc7) and /Documentation/driver-api/dmaengine/client.rst (Version linux-5.12.19)


  1 ====================                                1 ====================
  2 DMA Engine API Guide                                2 DMA Engine API Guide
  3 ====================                                3 ====================
  4                                                     4 
  5 Vinod Koul <vinod dot koul at intel.com>            5 Vinod Koul <vinod dot koul at intel.com>
  6                                                     6 
  7 .. note:: For DMA Engine usage in async_tx ple      7 .. note:: For DMA Engine usage in async_tx please see:
  8           ``Documentation/crypto/async-tx-api.      8           ``Documentation/crypto/async-tx-api.rst``
  9                                                     9 
 10                                                    10 
 11 Below is a guide to device driver writers on h     11 Below is a guide to device driver writers on how to use the Slave-DMA API of the
 12 DMA Engine. This is applicable only for slave      12 DMA Engine. This is applicable only for slave DMA usage only.
 13                                                    13 
 14 DMA usage                                          14 DMA usage
 15 =========                                          15 =========
 16                                                    16 
 17 The slave DMA usage consists of following step     17 The slave DMA usage consists of following steps:
 18                                                    18 
 19 - Allocate a DMA slave channel                     19 - Allocate a DMA slave channel
 20                                                    20 
 21 - Set slave and controller specific parameters     21 - Set slave and controller specific parameters
 22                                                    22 
 23 - Get a descriptor for transaction                 23 - Get a descriptor for transaction
 24                                                    24 
 25 - Submit the transaction                           25 - Submit the transaction
 26                                                    26 
 27 - Issue pending requests and wait for callback     27 - Issue pending requests and wait for callback notification
 28                                                    28 
 29 The details of these operations are:               29 The details of these operations are:
 30                                                    30 
 31 1. Allocate a DMA slave channel                    31 1. Allocate a DMA slave channel
 32                                                    32 
 33    Channel allocation is slightly different in     33    Channel allocation is slightly different in the slave DMA context,
 34    client drivers typically need a channel fro     34    client drivers typically need a channel from a particular DMA
 35    controller only and even in some cases a sp     35    controller only and even in some cases a specific channel is desired.
 36    To request a channel dma_request_chan() API     36    To request a channel dma_request_chan() API is used.
 37                                                    37 
 38    Interface:                                      38    Interface:
 39                                                    39 
 40    .. code-block:: c                               40    .. code-block:: c
 41                                                    41 
 42       struct dma_chan *dma_request_chan(struct     42       struct dma_chan *dma_request_chan(struct device *dev, const char *name);
 43                                                    43 
 44    Which will find and return the ``name`` DMA     44    Which will find and return the ``name`` DMA channel associated with the 'dev'
 45    device. The association is done via DT, ACP     45    device. The association is done via DT, ACPI or board file based
 46    dma_slave_map matching table.                   46    dma_slave_map matching table.
 47                                                    47 
 48    A channel allocated via this interface is e     48    A channel allocated via this interface is exclusive to the caller,
 49    until dma_release_channel() is called.          49    until dma_release_channel() is called.
 50                                                    50 
 51 2. Set slave and controller specific parameter     51 2. Set slave and controller specific parameters
 52                                                    52 
 53    Next step is always to pass some specific i     53    Next step is always to pass some specific information to the DMA
 54    driver. Most of the generic information whi     54    driver. Most of the generic information which a slave DMA can use
 55    is in struct dma_slave_config. This allows      55    is in struct dma_slave_config. This allows the clients to specify
 56    DMA direction, DMA addresses, bus widths, D     56    DMA direction, DMA addresses, bus widths, DMA burst lengths etc
 57    for the peripheral.                             57    for the peripheral.
 58                                                    58 
 59    If some DMA controllers have more parameter     59    If some DMA controllers have more parameters to be sent then they
 60    should try to embed struct dma_slave_config     60    should try to embed struct dma_slave_config in their controller
 61    specific structure. That gives flexibility      61    specific structure. That gives flexibility to client to pass more
 62    parameters, if required.                        62    parameters, if required.
 63                                                    63 
 64    Interface:                                      64    Interface:
 65                                                    65 
 66    .. code-block:: c                               66    .. code-block:: c
 67                                                    67 
 68       int dmaengine_slave_config(struct dma_ch     68       int dmaengine_slave_config(struct dma_chan *chan,
 69                         struct dma_slave_confi     69                         struct dma_slave_config *config)
 70                                                    70 
 71    Please see the dma_slave_config structure d     71    Please see the dma_slave_config structure definition in dmaengine.h
 72    for a detailed explanation of the struct me     72    for a detailed explanation of the struct members. Please note
 73    that the 'direction' member will be going a     73    that the 'direction' member will be going away as it duplicates the
 74    direction given in the prepare call.            74    direction given in the prepare call.
 75                                                    75 
 76 3. Get a descriptor for transaction                76 3. Get a descriptor for transaction
 77                                                    77 
 78   For slave usage the various modes of slave t     78   For slave usage the various modes of slave transfers supported by the
 79   DMA-engine are:                                  79   DMA-engine are:
 80                                                    80 
 81   - slave_sg: DMA a list of scatter gather buf     81   - slave_sg: DMA a list of scatter gather buffers from/to a peripheral
 82                                                    82 
 83   - peripheral_dma_vec: DMA an array of scatte << 
 84     peripheral. Similar to slave_sg, but uses  << 
 85     structures instead of a scatterlist.       << 
 86                                                << 
 87   - dma_cyclic: Perform a cyclic DMA operation     83   - dma_cyclic: Perform a cyclic DMA operation from/to a peripheral till the
 88     operation is explicitly stopped.               84     operation is explicitly stopped.
 89                                                    85 
 90   - interleaved_dma: This is common to Slave a     86   - interleaved_dma: This is common to Slave as well as M2M clients. For slave
 91     address of devices' fifo could be already      87     address of devices' fifo could be already known to the driver.
 92     Various types of operations could be expre     88     Various types of operations could be expressed by setting
 93     appropriate values to the 'dma_interleaved     89     appropriate values to the 'dma_interleaved_template' members. Cyclic
 94     interleaved DMA transfers are also possibl     90     interleaved DMA transfers are also possible if supported by the channel by
 95     setting the DMA_PREP_REPEAT transfer flag.     91     setting the DMA_PREP_REPEAT transfer flag.
 96                                                    92 
 97   A non-NULL return of this transfer API repre     93   A non-NULL return of this transfer API represents a "descriptor" for
 98   the given transaction.                           94   the given transaction.
 99                                                    95 
100   Interface:                                       96   Interface:
101                                                    97 
102   .. code-block:: c                                98   .. code-block:: c
103                                                    99 
104      struct dma_async_tx_descriptor *dmaengine    100      struct dma_async_tx_descriptor *dmaengine_prep_slave_sg(
105                 struct dma_chan *chan, struct     101                 struct dma_chan *chan, struct scatterlist *sgl,
106                 unsigned int sg_len, enum dma_    102                 unsigned int sg_len, enum dma_data_direction direction,
107                 unsigned long flags);             103                 unsigned long flags);
108                                                   104 
109      struct dma_async_tx_descriptor *dmaengine << 
110                 struct dma_chan *chan, const s << 
111                 size_t nents, enum dma_data_di << 
112                 unsigned long flags);          << 
113                                                << 
114      struct dma_async_tx_descriptor *dmaengine    105      struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic(
115                 struct dma_chan *chan, dma_add    106                 struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
116                 size_t period_len, enum dma_da    107                 size_t period_len, enum dma_data_direction direction);
117                                                   108 
118      struct dma_async_tx_descriptor *dmaengine    109      struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma(
119                 struct dma_chan *chan, struct     110                 struct dma_chan *chan, struct dma_interleaved_template *xt,
120                 unsigned long flags);             111                 unsigned long flags);
121                                                   112 
122   The peripheral driver is expected to have ma    113   The peripheral driver is expected to have mapped the scatterlist for
123   the DMA operation prior to calling dmaengine    114   the DMA operation prior to calling dmaengine_prep_slave_sg(), and must
124   keep the scatterlist mapped until the DMA op    115   keep the scatterlist mapped until the DMA operation has completed.
125   The scatterlist must be mapped using the DMA    116   The scatterlist must be mapped using the DMA struct device.
126   If a mapping needs to be synchronized later,    117   If a mapping needs to be synchronized later, dma_sync_*_for_*() must be
127   called using the DMA struct device, too.        118   called using the DMA struct device, too.
128   So, normal setup should look like this:         119   So, normal setup should look like this:
129                                                   120 
130   .. code-block:: c                               121   .. code-block:: c
131                                                   122 
132      struct device *dma_dev = dmaengine_get_dm    123      struct device *dma_dev = dmaengine_get_dma_device(chan);
133                                                   124 
134      nr_sg = dma_map_sg(dma_dev, sgl, sg_len);    125      nr_sg = dma_map_sg(dma_dev, sgl, sg_len);
135         if (nr_sg == 0)                           126         if (nr_sg == 0)
136                 /* error */                       127                 /* error */
137                                                   128 
138         desc = dmaengine_prep_slave_sg(chan, s    129         desc = dmaengine_prep_slave_sg(chan, sgl, nr_sg, direction, flags);
139                                                   130 
140   Once a descriptor has been obtained, the cal    131   Once a descriptor has been obtained, the callback information can be
141   added and the descriptor must then be submit    132   added and the descriptor must then be submitted. Some DMA engine
142   drivers may hold a spinlock between a succes    133   drivers may hold a spinlock between a successful preparation and
143   submission so it is important that these two    134   submission so it is important that these two operations are closely
144   paired.                                         135   paired.
145                                                   136 
146   .. note::                                       137   .. note::
147                                                   138 
148      Although the async_tx API specifies that     139      Although the async_tx API specifies that completion callback
149      routines cannot submit any new operations    140      routines cannot submit any new operations, this is not the
150      case for slave/cyclic DMA.                   141      case for slave/cyclic DMA.
151                                                   142 
152      For slave DMA, the subsequent transaction    143      For slave DMA, the subsequent transaction may not be available
153      for submission prior to callback function    144      for submission prior to callback function being invoked, so
154      slave DMA callbacks are permitted to prep    145      slave DMA callbacks are permitted to prepare and submit a new
155      transaction.                                 146      transaction.
156                                                   147 
157      For cyclic DMA, a callback function may w    148      For cyclic DMA, a callback function may wish to terminate the
158      DMA via dmaengine_terminate_async().         149      DMA via dmaengine_terminate_async().
159                                                   150 
160      Therefore, it is important that DMA engin    151      Therefore, it is important that DMA engine drivers drop any
161      locks before calling the callback functio    152      locks before calling the callback function which may cause a
162      deadlock.                                    153      deadlock.
163                                                   154 
164      Note that callbacks will always be invoke    155      Note that callbacks will always be invoked from the DMA
165      engines tasklet, never from interrupt con    156      engines tasklet, never from interrupt context.
166                                                   157 
167   **Optional: per descriptor metadata**           158   **Optional: per descriptor metadata**
168                                                   159 
169   DMAengine provides two ways for metadata sup    160   DMAengine provides two ways for metadata support.
170                                                   161 
171   DESC_METADATA_CLIENT                            162   DESC_METADATA_CLIENT
172                                                   163 
173     The metadata buffer is allocated/provided     164     The metadata buffer is allocated/provided by the client driver and it is
174     attached to the descriptor.                   165     attached to the descriptor.
175                                                   166 
176   .. code-block:: c                               167   .. code-block:: c
177                                                   168 
178      int dmaengine_desc_attach_metadata(struct    169      int dmaengine_desc_attach_metadata(struct dma_async_tx_descriptor *desc,
179                                    void *data,    170                                    void *data, size_t len);
180                                                   171 
181   DESC_METADATA_ENGINE                            172   DESC_METADATA_ENGINE
182                                                   173 
183     The metadata buffer is allocated/managed b    174     The metadata buffer is allocated/managed by the DMA driver. The client
184     driver can ask for the pointer, maximum si    175     driver can ask for the pointer, maximum size and the currently used size of
185     the metadata and can directly update or re    176     the metadata and can directly update or read it.
186                                                   177 
187     Because the DMA driver manages the memory  !! 178     Becasue the DMA driver manages the memory area containing the metadata,
188     clients must make sure that they do not tr    179     clients must make sure that they do not try to access or get the pointer
189     after their transfer completion callback h    180     after their transfer completion callback has run for the descriptor.
190     If no completion callback has been defined    181     If no completion callback has been defined for the transfer, then the
191     metadata must not be accessed after issue_    182     metadata must not be accessed after issue_pending.
192     In other words: if the aim is to read back    183     In other words: if the aim is to read back metadata after the transfer is
193     completed, then the client must use comple    184     completed, then the client must use completion callback.
194                                                   185 
195   .. code-block:: c                               186   .. code-block:: c
196                                                   187 
197      void *dmaengine_desc_get_metadata_ptr(str    188      void *dmaengine_desc_get_metadata_ptr(struct dma_async_tx_descriptor *desc,
198                 size_t *payload_len, size_t *m    189                 size_t *payload_len, size_t *max_len);
199                                                   190 
200      int dmaengine_desc_set_metadata_len(struc    191      int dmaengine_desc_set_metadata_len(struct dma_async_tx_descriptor *desc,
201                 size_t payload_len);              192                 size_t payload_len);
202                                                   193 
203   Client drivers can query if a given mode is     194   Client drivers can query if a given mode is supported with:
204                                                   195 
205   .. code-block:: c                               196   .. code-block:: c
206                                                   197 
207      bool dmaengine_is_metadata_mode_supported    198      bool dmaengine_is_metadata_mode_supported(struct dma_chan *chan,
208                 enum dma_desc_metadata_mode mo    199                 enum dma_desc_metadata_mode mode);
209                                                   200 
210   Depending on the used mode client drivers mu    201   Depending on the used mode client drivers must follow different flow.
211                                                   202 
212   DESC_METADATA_CLIENT                            203   DESC_METADATA_CLIENT
213                                                   204 
214     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:            205     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
215                                                   206 
216       1. prepare the descriptor (dmaengine_pre    207       1. prepare the descriptor (dmaengine_prep_*)
217          construct the metadata in the client'    208          construct the metadata in the client's buffer
218       2. use dmaengine_desc_attach_metadata()     209       2. use dmaengine_desc_attach_metadata() to attach the buffer to the
219          descriptor                               210          descriptor
220       3. submit the transfer                      211       3. submit the transfer
221                                                   212 
222     - DMA_DEV_TO_MEM:                             213     - DMA_DEV_TO_MEM:
223                                                   214 
224       1. prepare the descriptor (dmaengine_pre    215       1. prepare the descriptor (dmaengine_prep_*)
225       2. use dmaengine_desc_attach_metadata()     216       2. use dmaengine_desc_attach_metadata() to attach the buffer to the
226          descriptor                               217          descriptor
227       3. submit the transfer                      218       3. submit the transfer
228       4. when the transfer is completed, the m    219       4. when the transfer is completed, the metadata should be available in the
229          attached buffer                          220          attached buffer
230                                                   221 
231   DESC_METADATA_ENGINE                            222   DESC_METADATA_ENGINE
232                                                   223 
233     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:            224     - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
234                                                   225 
235       1. prepare the descriptor (dmaengine_pre    226       1. prepare the descriptor (dmaengine_prep_*)
236       2. use dmaengine_desc_get_metadata_ptr()    227       2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the
237          engine's metadata area                   228          engine's metadata area
238       3. update the metadata at the pointer       229       3. update the metadata at the pointer
239       4. use dmaengine_desc_set_metadata_len()    230       4. use dmaengine_desc_set_metadata_len()  to tell the DMA engine the
240          amount of data the client has placed     231          amount of data the client has placed into the metadata buffer
241       5. submit the transfer                      232       5. submit the transfer
242                                                   233 
243     - DMA_DEV_TO_MEM:                             234     - DMA_DEV_TO_MEM:
244                                                   235 
245       1. prepare the descriptor (dmaengine_pre    236       1. prepare the descriptor (dmaengine_prep_*)
246       2. submit the transfer                      237       2. submit the transfer
247       3. on transfer completion, use dmaengine    238       3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get
248          the pointer to the engine's metadata     239          the pointer to the engine's metadata area
249       4. read out the metadata from the pointe    240       4. read out the metadata from the pointer
250                                                   241 
251   .. note::                                       242   .. note::
252                                                   243 
253      When DESC_METADATA_ENGINE mode is used th    244      When DESC_METADATA_ENGINE mode is used the metadata area for the descriptor
254      is no longer valid after the transfer has    245      is no longer valid after the transfer has been completed (valid up to the
255      point when the completion callback return    246      point when the completion callback returns if used).
256                                                   247 
257      Mixed use of DESC_METADATA_CLIENT / DESC_    248      Mixed use of DESC_METADATA_CLIENT / DESC_METADATA_ENGINE is not allowed,
258      client drivers must use either of the mod    249      client drivers must use either of the modes per descriptor.
259                                                   250 
260 4. Submit the transaction                         251 4. Submit the transaction
261                                                   252 
262    Once the descriptor has been prepared and t    253    Once the descriptor has been prepared and the callback information
263    added, it must be placed on the DMA engine     254    added, it must be placed on the DMA engine drivers pending queue.
264                                                   255 
265    Interface:                                     256    Interface:
266                                                   257 
267    .. code-block:: c                              258    .. code-block:: c
268                                                   259 
269       dma_cookie_t dmaengine_submit(struct dma    260       dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc)
270                                                   261 
271    This returns a cookie can be used to check     262    This returns a cookie can be used to check the progress of DMA engine
272    activity via other DMA engine calls not cov    263    activity via other DMA engine calls not covered in this document.
273                                                   264 
274    dmaengine_submit() will not start the DMA o    265    dmaengine_submit() will not start the DMA operation, it merely adds
275    it to the pending queue. For this, see step    266    it to the pending queue. For this, see step 5, dma_async_issue_pending.
276                                                   267 
277    .. note::                                      268    .. note::
278                                                   269 
279       After calling ``dmaengine_submit()`` the    270       After calling ``dmaengine_submit()`` the submitted transfer descriptor
280       (``struct dma_async_tx_descriptor``) bel    271       (``struct dma_async_tx_descriptor``) belongs to the DMA engine.
281       Consequently, the client must consider i    272       Consequently, the client must consider invalid the pointer to that
282       descriptor.                                 273       descriptor.
283                                                   274 
284 5. Issue pending DMA requests and wait for cal    275 5. Issue pending DMA requests and wait for callback notification
285                                                   276 
286    The transactions in the pending queue can b    277    The transactions in the pending queue can be activated by calling the
287    issue_pending API. If channel is idle then     278    issue_pending API. If channel is idle then the first transaction in
288    queue is started and subsequent ones queued    279    queue is started and subsequent ones queued up.
289                                                   280 
290    On completion of each DMA operation, the ne    281    On completion of each DMA operation, the next in queue is started and
291    a tasklet triggered. The tasklet will then     282    a tasklet triggered. The tasklet will then call the client driver
292    completion callback routine for notificatio    283    completion callback routine for notification, if set.
293                                                   284 
294    Interface:                                     285    Interface:
295                                                   286 
296    .. code-block:: c                              287    .. code-block:: c
297                                                   288 
298       void dma_async_issue_pending(struct dma_    289       void dma_async_issue_pending(struct dma_chan *chan);
299                                                   290 
300 Further APIs                                      291 Further APIs
301 ------------                                      292 ------------
302                                                   293 
303 1. Terminate APIs                                 294 1. Terminate APIs
304                                                   295 
305    .. code-block:: c                              296    .. code-block:: c
306                                                   297 
307       int dmaengine_terminate_sync(struct dma_    298       int dmaengine_terminate_sync(struct dma_chan *chan)
308       int dmaengine_terminate_async(struct dma    299       int dmaengine_terminate_async(struct dma_chan *chan)
309       int dmaengine_terminate_all(struct dma_c    300       int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */
310                                                   301 
311    This causes all activity for the DMA channe    302    This causes all activity for the DMA channel to be stopped, and may
312    discard data in the DMA FIFO which hasn't b    303    discard data in the DMA FIFO which hasn't been fully transferred.
313    No callback functions will be called for an    304    No callback functions will be called for any incomplete transfers.
314                                                   305 
315    Two variants of this function are available    306    Two variants of this function are available.
316                                                   307 
317    dmaengine_terminate_async() might not wait     308    dmaengine_terminate_async() might not wait until the DMA has been fully
318    stopped or until any running complete callb    309    stopped or until any running complete callbacks have finished. But it is
319    possible to call dmaengine_terminate_async(    310    possible to call dmaengine_terminate_async() from atomic context or from
320    within a complete callback. dmaengine_synch    311    within a complete callback. dmaengine_synchronize() must be called before it
321    is safe to free the memory accessed by the     312    is safe to free the memory accessed by the DMA transfer or free resources
322    accessed from within the complete callback.    313    accessed from within the complete callback.
323                                                   314 
324    dmaengine_terminate_sync() will wait for th    315    dmaengine_terminate_sync() will wait for the transfer and any running
325    complete callbacks to finish before it retu    316    complete callbacks to finish before it returns. But the function must not be
326    called from atomic context or from within a    317    called from atomic context or from within a complete callback.
327                                                   318 
328    dmaengine_terminate_all() is deprecated and    319    dmaengine_terminate_all() is deprecated and should not be used in new code.
329                                                   320 
330 2. Pause API                                      321 2. Pause API
331                                                   322 
332    .. code-block:: c                              323    .. code-block:: c
333                                                   324 
334       int dmaengine_pause(struct dma_chan *cha    325       int dmaengine_pause(struct dma_chan *chan)
335                                                   326 
336    This pauses activity on the DMA channel wit    327    This pauses activity on the DMA channel without data loss.
337                                                   328 
338 3. Resume API                                     329 3. Resume API
339                                                   330 
340    .. code-block:: c                              331    .. code-block:: c
341                                                   332 
342        int dmaengine_resume(struct dma_chan *c    333        int dmaengine_resume(struct dma_chan *chan)
343                                                   334 
344    Resume a previously paused DMA channel. It     335    Resume a previously paused DMA channel. It is invalid to resume a
345    channel which is not currently paused.         336    channel which is not currently paused.
346                                                   337 
347 4. Check Txn complete                             338 4. Check Txn complete
348                                                   339 
349    .. code-block:: c                              340    .. code-block:: c
350                                                   341 
351       enum dma_status dma_async_is_tx_complete    342       enum dma_status dma_async_is_tx_complete(struct dma_chan *chan,
352                 dma_cookie_t cookie, dma_cooki    343                 dma_cookie_t cookie, dma_cookie_t *last, dma_cookie_t *used)
353                                                   344 
354    This can be used to check the status of the    345    This can be used to check the status of the channel. Please see
355    the documentation in include/linux/dmaengin    346    the documentation in include/linux/dmaengine.h for a more complete
356    description of this API.                       347    description of this API.
357                                                   348 
358    This can be used in conjunction with dma_as    349    This can be used in conjunction with dma_async_is_complete() and
359    the cookie returned from dmaengine_submit()    350    the cookie returned from dmaengine_submit() to check for
360    completion of a specific DMA transaction.      351    completion of a specific DMA transaction.
361                                                   352 
362    .. note::                                      353    .. note::
363                                                   354 
364       Not all DMA engine drivers can return re    355       Not all DMA engine drivers can return reliable information for
365       a running DMA channel. It is recommended    356       a running DMA channel. It is recommended that DMA engine users
366       pause or stop (via dmaengine_terminate_a    357       pause or stop (via dmaengine_terminate_all()) the channel before
367       using this API.                             358       using this API.
368                                                   359 
369 5. Synchronize termination API                    360 5. Synchronize termination API
370                                                   361 
371    .. code-block:: c                              362    .. code-block:: c
372                                                   363 
373       void dmaengine_synchronize(struct dma_ch    364       void dmaengine_synchronize(struct dma_chan *chan)
374                                                   365 
375    Synchronize the termination of the DMA chan    366    Synchronize the termination of the DMA channel to the current context.
376                                                   367 
377    This function should be used after dmaengin    368    This function should be used after dmaengine_terminate_async() to synchronize
378    the termination of the DMA channel to the c    369    the termination of the DMA channel to the current context. The function will
379    wait for the transfer and any running compl    370    wait for the transfer and any running complete callbacks to finish before it
380    returns.                                       371    returns.
381                                                   372 
382    If dmaengine_terminate_async() is used to s    373    If dmaengine_terminate_async() is used to stop the DMA channel this function
383    must be called before it is safe to free me    374    must be called before it is safe to free memory accessed by previously
384    submitted descriptors or to free any resour    375    submitted descriptors or to free any resources accessed within the complete
385    callback of previously submitted descriptor    376    callback of previously submitted descriptors.
386                                                   377 
387    The behavior of this function is undefined     378    The behavior of this function is undefined if dma_async_issue_pending() has
388    been called between dmaengine_terminate_asy    379    been called between dmaengine_terminate_async() and this function.
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php