重命名 AX88772C_eeprom/asix.c 为 asix_mac.c

hc

2024-09-20 a36159eec6ca17402b0e146b86efaf76568dc353

 kernel/Documentation/driver-api/dmaengine/client.rst
..
..
@@ -5,7 +5,7 @@
5
5
 Vinod Koul <vinod dot koul at intel.com>
6
6
 
7
7
 .. note:: For DMA Engine usage in async_tx please see:
8
-          ``Documentation/crypto/async-tx-api.txt``
8
+          ``Documentation/crypto/async-tx-api.rst``
9
9
 
10
10
 
11
11
 Below is a guide to device driver writers on how to use the Slave-DMA API of the
..
..
@@ -86,7 +86,9 @@
86
86
   - interleaved_dma: This is common to Slave as well as M2M clients. For slave
87
87
     address of devices' fifo could be already known to the driver.
88
88
     Various types of operations could be expressed by setting
89
-    appropriate values to the 'dma_interleaved_template' members.
89
+    appropriate values to the 'dma_interleaved_template' members. Cyclic
90
+    interleaved DMA transfers are also possible if supported by the channel by
91
+    setting the DMA_PREP_REPEAT transfer flag.
90
92
 
91
93
   A non-NULL return of this transfer API represents a "descriptor" for
92
94
   the given transaction.
..
..
@@ -151,6 +153,99 @@
151
153
      Note that callbacks will always be invoked from the DMA
152
154
      engines tasklet, never from interrupt context.
153
155
 
156
+  **Optional: per descriptor metadata**
157
+
158
+  DMAengine provides two ways for metadata support.
159
+
160
+  DESC_METADATA_CLIENT
161
+
162
+    The metadata buffer is allocated/provided by the client driver and it is
163
+    attached to the descriptor.
164
+
165
+  .. code-block:: c
166
+
167
+     int dmaengine_desc_attach_metadata(struct dma_async_tx_descriptor *desc,
168
+				   void *data, size_t len);
169
+
170
+  DESC_METADATA_ENGINE
171
+
172
+    The metadata buffer is allocated/managed by the DMA driver. The client
173
+    driver can ask for the pointer, maximum size and the currently used size of
174
+    the metadata and can directly update or read it.
175
+
176
+    Becasue the DMA driver manages the memory area containing the metadata,
177
+    clients must make sure that they do not try to access or get the pointer
178
+    after their transfer completion callback has run for the descriptor.
179
+    If no completion callback has been defined for the transfer, then the
180
+    metadata must not be accessed after issue_pending.
181
+    In other words: if the aim is to read back metadata after the transfer is
182
+    completed, then the client must use completion callback.
183
+
184
+  .. code-block:: c
185
+
186
+     void *dmaengine_desc_get_metadata_ptr(struct dma_async_tx_descriptor *desc,
187
+		size_t *payload_len, size_t *max_len);
188
+
189
+     int dmaengine_desc_set_metadata_len(struct dma_async_tx_descriptor *desc,
190
+		size_t payload_len);
191
+
192
+  Client drivers can query if a given mode is supported with:
193
+
194
+  .. code-block:: c
195
+
196
+     bool dmaengine_is_metadata_mode_supported(struct dma_chan *chan,
197
+		enum dma_desc_metadata_mode mode);
198
+
199
+  Depending on the used mode client drivers must follow different flow.
200
+
201
+  DESC_METADATA_CLIENT
202
+
203
+    - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
204
+
205
+      1. prepare the descriptor (dmaengine_prep_*)
206
+         construct the metadata in the client's buffer
207
+      2. use dmaengine_desc_attach_metadata() to attach the buffer to the
208
+         descriptor
209
+      3. submit the transfer
210
+
211
+    - DMA_DEV_TO_MEM:
212
+
213
+      1. prepare the descriptor (dmaengine_prep_*)
214
+      2. use dmaengine_desc_attach_metadata() to attach the buffer to the
215
+         descriptor
216
+      3. submit the transfer
217
+      4. when the transfer is completed, the metadata should be available in the
218
+         attached buffer
219
+
220
+  DESC_METADATA_ENGINE
221
+
222
+    - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
223
+
224
+      1. prepare the descriptor (dmaengine_prep_*)
225
+      2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the
226
+         engine's metadata area
227
+      3. update the metadata at the pointer
228
+      4. use dmaengine_desc_set_metadata_len()  to tell the DMA engine the
229
+         amount of data the client has placed into the metadata buffer
230
+      5. submit the transfer
231
+
232
+    - DMA_DEV_TO_MEM:
233
+
234
+      1. prepare the descriptor (dmaengine_prep_*)
235
+      2. submit the transfer
236
+      3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get
237
+         the pointer to the engine's metadata area
238
+      4. read out the metadata from the pointer
239
+
240
+  .. note::
241
+
242
+     When DESC_METADATA_ENGINE mode is used the metadata area for the descriptor
243
+     is no longer valid after the transfer has been completed (valid up to the
244
+     point when the completion callback returns if used).
245
+
246
+     Mixed use of DESC_METADATA_CLIENT / DESC_METADATA_ENGINE is not allowed,
247
+     client drivers must use either of the modes per descriptor.
248
+
154
249
 4. Submit the transaction
155
250
 
156
251
    Once the descriptor has been prepared and the callback information
..
..
@@ -168,6 +263,13 @@
168
263
    dmaengine_submit() will not start the DMA operation, it merely adds
169
264
    it to the pending queue. For this, see step 5, dma_async_issue_pending.
170
265
 
266
+   .. note::
267
+
268
+      After calling ``dmaengine_submit()`` the submitted transfer descriptor
269
+      (``struct dma_async_tx_descriptor``) belongs to the DMA engine.
270
+      Consequently, the client must consider invalid the pointer to that
271
+      descriptor.
272
+
171
273
 5. Issue pending DMA requests and wait for callback notification
172
274
 
173
275
    The transactions in the pending queue can be activated by calling the
..
..
@@ -184,8 +286,8 @@
184
286
 
185
287
       void dma_async_issue_pending(struct dma_chan *chan);
186
288
 
187
-Further APIs:
188
--------------
289
+Further APIs
290
+------------
189
291
 
190
292
 1. Terminate APIs
191
293