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