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.
128  * allocations will succeed.  The immediate commands in a transaction can
215 /* Map a TRE ring entry index to the transaction it is associated with */
227 /* Return the transaction mapped to a given ring entry */
235 /* Return the oldest completed transaction for a channel (or null) */
250 /* Move a transaction from allocated to committed state */
256 	/* This allocated transaction is now committed */  in gsi_trans_move_committed()
287 /* Move a transaction from completed to polled state */
293 	/* This completed transaction is now polled */  in gsi_trans_move_polled()
331 /* Allocate a GSI transaction on a channel */
346 	/* If we can't reserve the TREs for the transaction, we're done */  in gsi_channel_trans_alloc()
354 	/* Initialize non-zero fields in the transaction */  in gsi_channel_trans_alloc()
367 	/* This free transaction is now allocated */  in gsi_channel_trans_alloc()
373 /* Free a previously-allocated transaction */
394 	/* This transaction is now free */  in gsi_trans_free()
398 	 * (if present) info[] arrays, plus the transaction itself.  in gsi_trans_free()
403 /* Add an immediate command to a transaction */
417 	 * When a transaction completes, the SGL is normally unmapped.  in gsi_trans_cmd_add()
418 	 * A command transaction has direction DMA_NONE, which tells  in gsi_trans_cmd_add()
434 /* Add a page transfer to a transaction.  It will fill the only TRE. */
451 	trans->used_count++;	/* Transaction now owns the (DMA mapped) page */  in gsi_trans_page_add()
456 /* Add an SKB transfer to a transaction.  No other TREs will be used. */
478 	/* Transaction now owns the (DMA mapped) skb */  in gsi_trans_skb_add()
532  * __gsi_trans_commit() - Common GSI transaction commit code
533  * @trans:	Transaction to commit
537  * Maps a transaction pointer to the last ring entry used for the transaction,
538  * so it can be recovered when it completes.  Moves the transaction to
579 	/* Associate the TRE with the transaction */  in __gsi_trans_commit()
600 /* Commit a GSI transaction */
609 /* Commit a GSI transaction and wait for it to complete */
625 /* Process the completion of a transaction; called while polling */
700 /* Initialize a channel's GSI transaction info */
715 	 * outstanding transactions and their resources.  A transaction  in gsi_channel_trans_init()
717 	 * for what the transaction might need.  in gsi_channel_trans_init()
724 	 * Worst case is one TRE per transaction (but we actually limit  in gsi_channel_trans_init()
742 	 * the event (which will be the last one used by the transaction).  in gsi_channel_trans_init()
743 	 * Each entry in this map records the transaction associated  in gsi_channel_trans_init()
753 	/* A transaction uses a scatterlist array to represent the data  in gsi_channel_trans_init()
754 	 * transfers implemented by the transaction.  Each scatterlist  in gsi_channel_trans_init()
755 	 * element is used to fill a single TRE when the transaction is  in gsi_channel_trans_init()