24  * A GSI transaction abstracts the behavior of a GSI channel by representing
28  * by the GSI transaction core, allowing users to simply describe operations
29  * to be performed.  When a transaction has completed a callback function
31  * cleanup of resources associated with the transaction.
33  * To perform an operation (or set of them), a user of the GSI transaction
34  * interface allocates a transaction, indicating the number of TREs required
36  * for use in the transaction and the allocation succeeds.  This way
39  * transaction are also allocated when the transaction is allocated.
41  * Operations performed as part of a transaction are represented in an array
42  * of Linux scatterlist structures, allocated with the transaction.  These
44  * transaction.  If a buffer in an operation must be mapped for DMA, this is
45  * done at the time it is added to the transaction.  It is possible for a
47  * transaction should simply be freed; this correctly releases resources
48  * associated with the transaction.
50  * Once all operations have been successfully added to a transaction, the
51  * transaction is committed.  Committing transfers ownership of the entire
52  * transaction to the GSI transaction core.  The GSI transaction code
56  * The last TRE in each transaction is marked to interrupt the AP when the
59  * TRE in the transaction is sufficient to indicate the full transaction
62  * When a transaction is complete, ipa_gsi_trans_complete() is called by the
64  * required before the transaction is freed.
131  * allocations will succeed.  The immediate commands in a transaction can
218 /* Map a TRE ring entry index to the transaction it is associated with */
230 /* Return the transaction mapped to a given ring entry */
238 /* Return the oldest completed transaction for a channel (or null) */
253 /* Move a transaction from allocated to committed state */
259 	/* This allocated transaction is now committed */  in gsi_trans_move_committed()
290 /* Move a transaction from completed to polled state */
296 	/* This completed transaction is now polled */  in gsi_trans_move_polled()
334 /* Allocate a GSI transaction on a channel */
349 	/* If we can't reserve the TREs for the transaction, we're done */  in gsi_channel_trans_alloc()
357 	/* Initialize non-zero fields in the transaction */  in gsi_channel_trans_alloc()
370 	/* This free transaction is now allocated */  in gsi_channel_trans_alloc()
376 /* Free a previously-allocated transaction */
397 	/* This transaction is now free */  in gsi_trans_free()
401 	 * (if present) info[] arrays, plus the transaction itself.  in gsi_trans_free()
406 /* Add an immediate command to a transaction */
420 	 * When a transaction completes, the SGL is normally unmapped.  in gsi_trans_cmd_add()
421 	 * A command transaction has direction DMA_NONE, which tells  in gsi_trans_cmd_add()
437 /* Add a page transfer to a transaction.  It will fill the only TRE. */
454 	trans->used_count++;	/* Transaction now owns the (DMA mapped) page */  in gsi_trans_page_add()
459 /* Add an SKB transfer to a transaction.  No other TREs will be used. */
481 	/* Transaction now owns the (DMA mapped) skb */  in gsi_trans_skb_add()
535  * __gsi_trans_commit() - Common GSI transaction commit code
536  * @trans:	Transaction to commit
540  * Maps a transaction pointer to the last ring entry used for the transaction,
541  * so it can be recovered when it completes.  Moves the transaction to
582 	/* Associate the TRE with the transaction */  in __gsi_trans_commit()
603 /* Commit a GSI transaction */
612 /* Commit a GSI transaction and wait for it to complete */
628 /* Process the completion of a transaction; called while polling */
703 /* Initialize a channel's GSI transaction info */
718 	 * outstanding transactions and their resources.  A transaction  in gsi_channel_trans_init()
720 	 * for what the transaction might need.  in gsi_channel_trans_init()
727 	 * Worst case is one TRE per transaction (but we actually limit  in gsi_channel_trans_init()
745 	 * the event (which will be the last one used by the transaction).  in gsi_channel_trans_init()
746 	 * Each entry in this map records the transaction associated  in gsi_channel_trans_init()
756 	/* A transaction uses a scatterlist array to represent the data  in gsi_channel_trans_init()
757 	 * transfers implemented by the transaction.  Each scatterlist  in gsi_channel_trans_init()
758 	 * element is used to fill a single TRE when the transaction is  in gsi_channel_trans_init()