1/* SPDX-License-Identifier: GPL-2.0 */
  2
  3/* Copyright (c) 2012-2018, The Linux Foundation. All rights reserved.
  4 * Copyright (C) 2019-2020 Linaro Ltd.
  5 */
  6#ifndef _GSI_TRANS_H_
  7#define _GSI_TRANS_H_
  8
  9#include <linux/types.h>
 10#include <linux/refcount.h>
 11#include <linux/completion.h>
 12#include <linux/dma-direction.h>
 13
 14#include "ipa_cmd.h"
 15
 16struct page;
 17struct scatterlist;
 18struct device;
 19struct sk_buff;
 20
 21struct gsi;
 22struct gsi_trans;
 23struct gsi_trans_pool;
 24
 25/**
 26 * struct gsi_trans - a GSI transaction
 27 *
 28 * Most fields in this structure for internal use by the transaction core code:
 29 * @links:	Links for channel transaction lists by state
 30 * @gsi:	GSI pointer
 31 * @channel_id: Channel number transaction is associated with
 32 * @cancelled:	If set by the core code, transaction was cancelled
 33 * @tre_count:	Number of TREs reserved for this transaction
 34 * @used:	Number of TREs *used* (could be less than tre_count)
 35 * @len:	Total # of transfer bytes represented in sgl[] (set by core)
 36 * @data:	Preserved but not touched by the core transaction code
 37 * @sgl:	An array of scatter/gather entries managed by core code
 38 * @info:	Array of command information structures (command channel)
 39 * @direction:	DMA transfer direction (DMA_NONE for commands)
 40 * @refcount:	Reference count used for destruction
 41 * @completion:	Completed when the transaction completes
 42 * @byte_count:	TX channel byte count recorded when transaction committed
 43 * @trans_count: Channel transaction count when committed (for BQL accounting)
 44 *
 45 * The size used for some fields in this structure were chosen to ensure
 46 * the full structure size is no larger than 128 bytes.
 47 */
 48struct gsi_trans {
 49	struct list_head links;		/* gsi_channel lists */
 50
 51	struct gsi *gsi;
 52	u8 channel_id;
 53
 54	bool cancelled;			/* true if transaction was cancelled */
 55
 56	u8 tre_count;			/* # TREs requested */
 57	u8 used;			/* # entries used in sgl[] */
 58	u32 len;			/* total # bytes across sgl[] */
 59
 60	void *data;
 61	struct scatterlist *sgl;
 62	struct ipa_cmd_info *info;	/* array of entries, or null */
 63	enum dma_data_direction direction;
 64
 65	refcount_t refcount;
 66	struct completion completion;
 67
 68	u64 byte_count;			/* channel byte_count when committed */
 69	u64 trans_count;		/* channel trans_count when committed */
 70};
 71
 72/**
 73 * gsi_trans_pool_init() - Initialize a pool of structures for transactions
 74 * @pool:	GSI transaction poll pointer
 75 * @size:	Size of elements in the pool
 76 * @count:	Minimum number of elements in the pool
 77 * @max_alloc:	Maximum number of elements allocated at a time from pool
 78 *
 79 * Return:	0 if successful, or a negative error code
 80 */
 81int gsi_trans_pool_init(struct gsi_trans_pool *pool, size_t size, u32 count,
 82			u32 max_alloc);
 83
 84/**
 85 * gsi_trans_pool_alloc() - Allocate one or more elements from a pool
 86 * @pool:	Pool pointer
 87 * @count:	Number of elements to allocate from the pool
 88 *
 89 * Return:	Virtual address of element(s) allocated from the pool
 90 */
 91void *gsi_trans_pool_alloc(struct gsi_trans_pool *pool, u32 count);
 92
 93/**
 94 * gsi_trans_pool_exit() - Inverse of gsi_trans_pool_init()
 95 * @pool:	Pool pointer
 96 */
 97void gsi_trans_pool_exit(struct gsi_trans_pool *pool);
 98
 99/**
100 * gsi_trans_pool_init_dma() - Initialize a pool of DMA-able structures
101 * @dev:	Device used for DMA
102 * @pool:	Pool pointer
103 * @size:	Size of elements in the pool
104 * @count:	Minimum number of elements in the pool
105 * @max_alloc:	Maximum number of elements allocated at a time from pool
106 *
107 * Return:	0 if successful, or a negative error code
108 *
109 * Structures in this pool reside in DMA-coherent memory.
110 */
111int gsi_trans_pool_init_dma(struct device *dev, struct gsi_trans_pool *pool,
112			    size_t size, u32 count, u32 max_alloc);
113
114/**
115 * gsi_trans_pool_alloc_dma() - Allocate an element from a DMA pool
116 * @pool:	DMA pool pointer
117 * @addr:	DMA address "handle" associated with the allocation
118 *
119 * Return:	Virtual address of element allocated from the pool
120 *
121 * Only one element at a time may be allocated from a DMA pool.
122 */
123void *gsi_trans_pool_alloc_dma(struct gsi_trans_pool *pool, dma_addr_t *addr);
124
125/**
126 * gsi_trans_pool_exit_dma() - Inverse of gsi_trans_pool_init_dma()
127 * @dev:	Device used for DMA
128 * @pool:	Pool pointer
129 */
130void gsi_trans_pool_exit_dma(struct device *dev, struct gsi_trans_pool *pool);
131
132/**
133 * gsi_channel_trans_alloc() - Allocate a GSI transaction on a channel
134 * @gsi:	GSI pointer
135 * @channel_id:	Channel the transaction is associated with
136 * @tre_count:	Number of elements in the transaction
137 * @direction:	DMA direction for entire SGL (or DMA_NONE)
138 *
139 * Return:	A GSI transaction structure, or a null pointer if all
140 *		available transactions are in use
141 */
142struct gsi_trans *gsi_channel_trans_alloc(struct gsi *gsi, u32 channel_id,
143					  u32 tre_count,
144					  enum dma_data_direction direction);
145
146/**
147 * gsi_trans_free() - Free a previously-allocated GSI transaction
148 * @trans:	Transaction to be freed
149 */
150void gsi_trans_free(struct gsi_trans *trans);
151
152/**
153 * gsi_trans_cmd_add() - Add an immediate command to a transaction
154 * @trans:	Transaction
155 * @buf:	Buffer pointer for command payload
156 * @size:	Number of bytes in buffer
157 * @addr:	DMA address for payload
158 * @direction:	Direction of DMA transfer (or DMA_NONE if none required)
159 * @opcode:	IPA immediate command opcode
160 */
161void gsi_trans_cmd_add(struct gsi_trans *trans, void *buf, u32 size,
162		       dma_addr_t addr, enum dma_data_direction direction,
163		       enum ipa_cmd_opcode opcode);
164
165/**
166 * gsi_trans_page_add() - Add a page transfer to a transaction
167 * @trans:	Transaction
168 * @page:	Page pointer
169 * @size:	Number of bytes (starting at offset) to transfer
170 * @offset:	Offset within page for start of transfer
171 */
172int gsi_trans_page_add(struct gsi_trans *trans, struct page *page, u32 size,
173		       u32 offset);
174
175/**
176 * gsi_trans_skb_add() - Add a socket transfer to a transaction
177 * @trans:	Transaction
178 * @skb:	Socket buffer for transfer (outbound)
179 *
180 * Return:	0, or -EMSGSIZE if socket data won't fit in transaction.
181 */
182int gsi_trans_skb_add(struct gsi_trans *trans, struct sk_buff *skb);
183
184/**
185 * gsi_trans_commit() - Commit a GSI transaction
186 * @trans:	Transaction to commit
187 * @ring_db:	Whether to tell the hardware about these queued transfers
188 */
189void gsi_trans_commit(struct gsi_trans *trans, bool ring_db);
190
191/**
192 * gsi_trans_commit_wait() - Commit a GSI transaction and wait for it
193 *			     to complete
194 * @trans:	Transaction to commit
195 */
196void gsi_trans_commit_wait(struct gsi_trans *trans);
197
198/**
199 * gsi_trans_commit_wait_timeout() - Commit a GSI transaction and wait for
200 *				     it to complete, with timeout
201 * @trans:	Transaction to commit
202 * @timeout:	Timeout period (in milliseconds)
203 */
204int gsi_trans_commit_wait_timeout(struct gsi_trans *trans,
205				  unsigned long timeout);
206
207/**
208 * gsi_trans_read_byte() - Issue a single byte read TRE on a channel
209 * @gsi:	GSI pointer
210 * @channel_id:	Channel on which to read a byte
211 * @addr:	DMA address into which to transfer the one byte
212 *
213 * This is not a transaction operation at all.  It's defined here because
214 * it needs to be done in coordination with other transaction activity.
215 */
216int gsi_trans_read_byte(struct gsi *gsi, u32 channel_id, dma_addr_t addr);
217
218/**
219 * gsi_trans_read_byte_done() - Clean up after a single byte read TRE
220 * @gsi:	GSI pointer
221 * @channel_id:	Channel on which byte was read
222 *
223 * This function needs to be called to signal that the work related
224 * to reading a byte initiated by gsi_trans_read_byte() is complete.
225 */
226void gsi_trans_read_byte_done(struct gsi *gsi, u32 channel_id);
227
228#endif /* _GSI_TRANS_H_ */